From bdf3398dac90a54d82aed65099290d51e92d4601 Mon Sep 17 00:00:00 2001 From: Michael Wallner Date: Fri, 28 Feb 2020 16:32:29 +0100 Subject: [PATCH] docs: ws --- docs/source/bin/memaslap.rst | 149 ++---------------- docs/source/bin/memcapable.rst | 25 +-- docs/source/bin/memcat.rst | 12 -- docs/source/bin/memcp.rst | 12 -- docs/source/bin/memdump.rst | 13 +- docs/source/bin/memerror.rst | 11 -- docs/source/bin/memexist.rst | 9 -- docs/source/bin/memflush.rst | 11 -- docs/source/bin/memparse.rst | 10 -- docs/source/bin/memping.rst | 9 -- docs/source/bin/memrm.rst | 13 -- docs/source/bin/memslap.rst | 12 +- docs/source/bin/memstat.rst | 14 +- docs/source/bin/memtouch.rst | 10 -- docs/source/index.rst | 1 - docs/source/libhashkit/hashkit_create.rst | 4 +- docs/source/libhashkit/hashkit_function.rst | 1 - docs/source/libmemcached.rst | 3 +- .../source/libmemcached/memcached_analyze.rst | 6 +- docs/source/libmemcached/memcached_append.rst | 19 +-- docs/source/libmemcached/memcached_auto.rst | 6 +- docs/source/libmemcached/memcached_cas.rst | 9 +- docs/source/libmemcached/memcached_create.rst | 23 ++- docs/source/libmemcached/memcached_delete.rst | 15 +- docs/source/libmemcached/memcached_dump.rst | 15 +- docs/source/libmemcached/memcached_exist.rst | 5 +- docs/source/libmemcached/memcached_fetch.rst | 14 +- docs/source/libmemcached/memcached_flush.rst | 12 +- .../libmemcached/memcached_flush_buffers.rst | 12 +- .../memcached_generate_hash_value.rst | 12 +- docs/source/libmemcached/memcached_get.rst | 25 ++- .../libmemcached/memcached_last_error.rst | 3 +- .../memcached_memory_allocators.rst | 17 +- docs/source/libmemcached/memcached_quit.rst | 8 +- .../libmemcached/memcached_result_st.rst | 13 +- docs/source/libmemcached/memcached_sasl.rst | 8 - .../libmemcached/memcached_server_st.rst | 8 +- .../source/libmemcached/memcached_servers.rst | 20 +-- docs/source/libmemcached/memcached_set.rst | 2 +- .../memcached_set_encoding_key.rst | 8 +- docs/source/libmemcached/memcached_stats.rst | 7 - docs/source/libmemcached/memcached_touch.rst | 8 +- .../libmemcached/memcached_user_data.rst | 11 -- .../libmemcached/memcached_verbosity.rst | 5 - .../source/libmemcached/memcached_version.rst | 15 +- .../libmemcachedutil/memcached_pool.rst | 20 +-- 46 files changed, 102 insertions(+), 543 deletions(-) diff --git a/docs/source/bin/memaslap.rst b/docs/source/bin/memaslap.rst index f323e524..4233e7fa 100644 --- a/docs/source/bin/memaslap.rst +++ b/docs/source/bin/memaslap.rst @@ -2,8 +2,6 @@ memaslap - Load testing and benchmarking a server ================================================== - --------- SYNOPSIS -------- @@ -15,11 +13,9 @@ memaslap [options] .. envvar:: MEMCACHED_SERVERS ------------ DESCRIPTION ----------- - :program:`memaslap` is a load generation and benchmark tool for memcached servers. It generates configurable workload such as threads, concurrency, connections, run time, overwrite, miss rate, key size, value size, get/set @@ -36,83 +32,49 @@ value size distribution, and command distribution by itself. You can specify servers via the :option:`memslap --servers` option or via the environment variable :envvar:`MEMCACHED_SERVERS`. - --------- FEATURES -------- - Memslap is developed to for the following purposes: - Manages network connections with libevent asynchronously. - - Set both TCP and UDP up to use non-blocking IO. - - Improves parallelism: higher performance in multi-threads environments. - - Improves time efficiency: faster processing speed. - - Generates key and value more efficiently; key size distribution and value size distribution are configurable. - - Supports get, multi-get, and set commands; command distribution is configurable. - - Supports controllable miss rate and overwrite rate. - - Supports data and expire-time verification. - - Supports dumping statistic information periodically. - - Supports thousands of TCP connections. - - Supports binary protocol. - - Supports facebook test (set with TCP and multi-get with UDP) and replication test. - - - -------- DETAILS ------- - Effective implementation of network. ____________________________________ - For memaslap, both TCP and UDP use non-blocking network IO. All the network events are managed by libevent as memcached. The network module of memaslap is similar to memcached. Libevent can ensure memaslap can handle network very efficiently. - Effective implementation of multi-threads and concurrency _________________________________________________________ - Memslap has the similar implementation of multi-threads to memcached. Memslap creates one or more self-governed threads; each thread is bound with one CPU core if the system tests setting CPU @@ -131,12 +93,10 @@ socket connection at any given time. Users can specify the number of concurrency and socket connections of each concurrency according to their expected workload. - Effective implementation of generating key and value ____________________________________________________ - -In order to improve time efficiency and space efficiency, +In order to improve time efficiency and space efficiency, memaslap creates a random characters table with 10M characters. All the suffixes of keys and values are generated from this random characters table. @@ -159,11 +119,9 @@ object from the window to do set operation or get operation. At the same time, each concurrency kicks objects out of its window and adds new object into it. - Simple but useful task scheduling _________________________________ - Memslap uses libevent to schedule all concurrent tasks of threads, and each concurrency schedules tasks based on the local task window. Memslap assumes that if each concurrency keeps the same @@ -191,11 +149,9 @@ cache layer. It causes the first cache layer to miss. So the user can specify the window size to get the expected miss rate of the first cache layer. - Useful implementation of multi-servers , UDP, TCP, multi-get and binary protocol ________________________________________________________________________________ - Because each thread is self-governed, memaslap can assign different threads to handle different memcached servers. This is just one of the ways in which memaslap tests multiple servers. The only @@ -219,44 +175,25 @@ one command from the server and reorders the response data. If some packages get lost, the waiting timeout mechanism can ensure half-baked packages will be discarded and the next command will be sent. - - ------ USAGE ----- - Below are some usage samples: - memaslap -s 127.0.0.1:11211 -S 5s - - memaslap -s 127.0.0.1:11211 -t 2m -v 0.2 -e 0.05 -b - - memaslap -s 127.0.0.1:11211 -F config -t 2m -w 40k -S 20s -o 0.2 - - memaslap -s 127.0.0.1:11211 -F config -t 2m -T 4 -c 128 -d 20 -P 40k - - memaslap -s 127.0.0.1:11211 -F config -t 2m -d 50 -a -n 40 - - memaslap -s 127.0.0.1:11211,127.0.0.1:11212 -F config -t 2m - - memaslap -s 127.0.0.1:11211,127.0.0.1:11212 -F config -t 2m -p 2 - - The user must specify one server at least to run memaslap. The rest of the parameters have default values, as shown below: @@ -284,11 +221,9 @@ TCP = true Limit throughput = false Facebook test = false Replication test = false - Key size, value size and command distribution. ______________________________________________ - All the distributions are read from the configuration file specified by user with "—cfg_cmd" option. If the user does not specify a configuration file, memaslap will run with the default distribution (key size = 64, @@ -306,11 +241,9 @@ Currently, memaslap only tests set and get commands. And it testss 100% set and 100% get. For 100% get, it will preset some objects to the server. - Multi-thread and concurrency ____________________________ - The high performance of memaslap benefits from the special schedule of thread and concurrency. It's important to specify the proper number of them. The default number of threads is 1; the default number of @@ -366,11 +299,9 @@ kops/s for a specific configuration, you can specify the throughput equal to or less than the maximum throughput using "--tps" option. - Window size ___________ - Most of the time, the user does not need to specify the window size. The default window size is 10k. For Schooner Memcached, the user can specify different window sizes to get different cache miss rates based on the test @@ -415,11 +346,9 @@ The formula for calculating window size for cache miss rate 5%: cache_size / concurrency / (key_size + value_size) \* 0.7 - Verification ____________ - Memslap testss both data verification and expire-time verification. The user can use "--verify=" or "-v" to specify the proportion of data verification. In theory, it testss 100% data verification. The @@ -428,16 +357,14 @@ expire-time verification. In theory, it testss 100% expire-time verification. Specify the "--verbose" options to get more detailed error information. -For example: --exp_verify=0.01 –verify=0.1 , it means that 1% of the objects +For example: --exp_verify=0.01 –verify=0.1 , it means that 1% of the objects set with expire-time, 10% of the objects gotten will be verified. If the objects are gotten, memaslap will verify the expire-time and value. - multi-servers and multi-config _______________________________ - Memslap testss multi-servers based on self-governed thread. There is a limitation that the number of servers cannot be greater than the number of threads. Memslap assigns one thread to handle one @@ -455,17 +382,15 @@ and 4 handle server 1 (10.1.1.2); and thread 2 and 5 handle server 2 All the threads and concurrencies in memaslap are self-governed. -So is memaslap. The user can start up several +So is memaslap. The user can start up several memaslap instances. The user can run memaslap on different client machines to communicate with the same memcached server at the same. It is recommended that the user start different memaslap on different machines using the same configuration. - Run with execute number mode or time mode _________________________________________ - The default memaslap runs with time mode. The default run time is 10 minutes. If it times out, memaslap will exit. Do not specify both execute number mode and time mode at the same time; just @@ -477,11 +402,9 @@ For example: --execute_number=100000 (It means that after running 100000 commands, the test will exit.) - Dump statistic information periodically. ________________________________________ - The user can use "--stat_freq=" or "-S" to specify the frequency. For example: @@ -493,11 +416,9 @@ seconds. For more information on the format of dumping statistic information, refer to "Format of Output" section. - Multi-get _________ - The user can use "--division=" or "-d" to specify multi-get keys count. Memslap by default does single get with TCP. Memslap also testss data verification and expire-time verification for multi-get. @@ -509,11 +430,9 @@ memaslap sends one "multi-get" to the server once. For the binary protocol, memaslap sends several single get commands together as "multi-get" to the server. - UDP and TCP ___________ - Memslap testss both UDP and TCP. For TCP, memaslap does not reconnect the memcached server if socket connections are lost. If all the socket connections are lost or memcached server crashes, @@ -530,11 +449,9 @@ memcached does not tests that. UDP doesn't tests reconnection. - Facebook test _____________ - Set data with TCP and multi-get with UDP. Specify the following options: "--facebook --division=50" @@ -554,11 +471,9 @@ objects once with the UDP socket. If you specify "--division=50", the key size must be less that 25 bytes because the UDP packet size is 1400 bytes. - Replication test ________________ - For replication test, the user must specify at least two memcached servers. The user can use "—rep_write=" option to enable feature. @@ -574,11 +489,9 @@ memaslap will only get objects from server 1. If server 0 comes back to life again, memaslap will reconnect server 0. If both server 0 and server 1 crash, memaslap will exit. - Supports thousands of TCP connections _____________________________________ - Start memaslap with "--conn_sock=" or "-n" to enable this feature. Make sure that your system can tests opening thousands of files and creating thousands of sockets. However, this feature does not tests @@ -593,11 +506,9 @@ thread has 16 concurrencies, each concurrency has 128 TCP socket connections, and the total number of TCP socket connections is 128 \* 128 = 16384. - Supports binary protocol ________________________ - Start memaslap with "--binary" or "-B" options to enable this feature. It testss all the above features except UDP, because the latest memcached 1.3.3 does not implement binary UDP protocol. @@ -611,20 +522,15 @@ memaslap does not tests UDP. In addition, memcached 1.3.3 does not tests multi-get. If you specify "--division=50" option, it just sends 50 get commands together as "multi-get" to the server. - - ------------------- Configuration file ------------------ - This section describes the format of the configuration file. By default when no configuration file is specified memaslap reads the default one located at ~/.memaslap.cnf. Below is a sample configuration file: - .. code-block:: perl --------------------------------------------------------------------------- @@ -699,49 +605,28 @@ Below is a sample configuration file: 0 0.1 1.0 0.9 - - ----------------- Format of output ---------------- - At the beginning, memaslap displays some configuration information as follows: - servers : 127.0.0.1:11211 - - threads count: 1 - - concurrency: 16 - - run time: 20s - - windows size: 10k - - set proportion: set_prop=0.10 - - get proportion: get_prop=0.90 - - Where _____ - - servers : "servers" The servers used by memaslap. @@ -786,7 +671,6 @@ get proportion The output of dynamic statistics is something like this: - .. code-block:: perl --------------------------------------------------------------------------------------------------------------------------------- @@ -817,13 +701,9 @@ The output of dynamic statistics is something like this: 117.93 195.60 --------------------------------------------------------------------------------------------------------------------------------- - - Where _____ - - Get Statistics Statistics information of get command @@ -910,7 +790,6 @@ Geo_dist At the end, memaslap will output something like this: - .. code-block:: perl --------------------------------------------------------------------------------------------------------------------------------- @@ -969,8 +848,6 @@ At the end, memaslap will output something like this: Where _____ - - Get Statistics Get statistics of response time @@ -1123,11 +1000,9 @@ Net_rate -------- OPTIONS ------- - -s, --servers= List one or more servers to connect. Servers count must be less than threads count. e.g.: --servers=localhost:1234,localhost:11211 @@ -1177,17 +1052,17 @@ OPTIONS The proportion of objects need overwrite, e.g.: --overwrite=0.01. Default never overwrite object. --R, --reconnect +-R, --reconnect Reconnect tests, when connection is closed it will be reconnected. --U, --udp +-U, --udp UDP tests, default memaslap uses TCP, TCP port and UDP port of server must be same. --a, --facebook +-a, --facebook Whether it enables facebook test feature, set with TCP and multi-get with UDP. --B, --binary +-B, --binary Whether it enables binary protocol. Default with ASCII protocol. -P, --tps= @@ -1196,21 +1071,18 @@ OPTIONS -p, --rep_write= The first nth servers can write data, e.g.: --rep_write=2. --b, --verbose +-b, --verbose Whether it outputs detailed information when verification fails. --h, --help +-h, --help Display this message and then exit. --V, --version +-V, --version Display the version of the application and then exit. - --------- EXAMPLES -------- - memaslap -s 127.0.0.1:11211 -S 5s memaslap -s 127.0.0.1:11211 -t 2m -v 0.2 -e 0.05 -b @@ -1225,7 +1097,6 @@ memaslap -s 127.0.0.1:11211,127.0.0.1:11212 -F config -t 2m memaslap -s 127.0.0.1:11211,127.0.0.1:11212 -F config -t 2m -p 2 --------- SEE ALSO -------- diff --git a/docs/source/bin/memcapable.rst b/docs/source/bin/memcapable.rst index da1a2e6c..f8290333 100644 --- a/docs/source/bin/memcapable.rst +++ b/docs/source/bin/memcapable.rst @@ -2,7 +2,6 @@ memcapable - Checking a Memcached server capabilities and compatibility ======================================================================= --------- SYNOPSIS -------- @@ -10,7 +9,6 @@ memcapable [options] .. program:: memcapable ------------ DESCRIPTION ----------- @@ -18,41 +16,34 @@ DESCRIPTION determine its capabilities by running the various commands and verifying the response. - ------------ LIMITATIONS ----------- - The current version of memcapable will only verify the binary protocol. - -------- OPTIONS ------- - .. option:: -h hostname - + Specify the hostname to connect to. The default is \ *localhost*\ .. option:: -p port - + Specify the port number to connect to. The default is \ *11211*\ - + .. option:: -c - + Generate a coredump when it detects an error from the server. - + .. option:: -v - + Print out the comparison when it detects an error from the server. - + .. option:: -t n - + Set the timeout from an IO operation to/from the server to \ *n*\ seconds. --------- SEE ALSO -------- diff --git a/docs/source/bin/memcat.rst b/docs/source/bin/memcat.rst index 00773ee0..c3a6b65e 100644 --- a/docs/source/bin/memcat.rst +++ b/docs/source/bin/memcat.rst @@ -2,9 +2,6 @@ memcat - "cat" data from a server ================================= - - --------- SYNOPSIS -------- @@ -12,26 +9,19 @@ memcat [options] key Copy a set of keys to stdout - .. program:: memcat - ------------ DESCRIPTION ----------- - :program:`memcat` outputs to stdout the value a single or multiple set of keys stored in a memcached(1) server. If any key is not found an error is returned. It is similar to the standard UNIX cat(1) utility. - -------- OPTIONS ------- - You can specify servers via the option: .. option:: --servers @@ -44,8 +34,6 @@ For a full list of operations run the tool with the option: .. option:: --help - --------- SEE ALSO -------- diff --git a/docs/source/bin/memcp.rst b/docs/source/bin/memcp.rst index a60008be..e67cd28e 100644 --- a/docs/source/bin/memcp.rst +++ b/docs/source/bin/memcp.rst @@ -2,11 +2,8 @@ memcp - Copy data to a server ============================= - Copies files to a collection of memcached servers - --------- SYNOPSIS -------- @@ -14,24 +11,18 @@ memcp [options] [file] [server] .. program:: memcp - ------------ DESCRIPTION ----------- - :program:`memcp` copies one or more files into memcached(1) servers. It is similar to the standard UNIX cp(1) command. The key names will be the names of the files, without any directory path. - -------- OPTIONS ------- - You can specify servers via the option: .. option:: --servers @@ -46,9 +37,6 @@ For a full list of operations run the tool with the option: .. option:: --help - - --------- SEE ALSO -------- diff --git a/docs/source/bin/memdump.rst b/docs/source/bin/memdump.rst index 8510605a..ed3c8004 100644 --- a/docs/source/bin/memdump.rst +++ b/docs/source/bin/memdump.rst @@ -2,11 +2,8 @@ memdump - Dumping your server ============================= - Dump a list of keys from a server. - --------- SYNOPSIS -------- @@ -14,28 +11,20 @@ memdump [options] .. program:: memdump ------------ DESCRIPTION ----------- - -:program:`memdump` dumps a list of "keys" from all servers that +:program:`memdump` dumps a list of "keys" from all servers that it is told to fetch from. Because memcached does not guarantee to provide all keys it is not possible to get a complete "dump". - -------- OPTIONS ------- - For a full list of operations run the tool with option: .. option:: --help - - --------- SEE ALSO -------- diff --git a/docs/source/bin/memerror.rst b/docs/source/bin/memerror.rst index 2a630060..d67c08f1 100644 --- a/docs/source/bin/memerror.rst +++ b/docs/source/bin/memerror.rst @@ -2,11 +2,8 @@ memerror - translate an error code to a string ============================================== - Translates a memcached error code into a string - --------- SYNOPSIS -------- @@ -14,27 +11,19 @@ memerror [options] [error code] .. program:: memerror ------------ DESCRIPTION ----------- - :program:`memerror` translates an error code from libmemcached(3) into a human readable string. - -------- OPTIONS ------- - For a full list of operations run the tool with option: .. option:: --help - - --------- SEE ALSO -------- diff --git a/docs/source/bin/memexist.rst b/docs/source/bin/memexist.rst index fd23a80b..c8542ac8 100644 --- a/docs/source/bin/memexist.rst +++ b/docs/source/bin/memexist.rst @@ -2,8 +2,6 @@ memexist - Check for the existence of a key =========================================== - --------- SYNOPSIS -------- @@ -11,19 +9,14 @@ memexist [options] [key] .. program:: memexist - ------------ DESCRIPTION ----------- :program:`memexist` checks for the existance of a key within a cluster. - -------- OPTIONS ------- - You can specify servers via the option: .. option:: --servers @@ -38,8 +31,6 @@ For a full list of operations run the tool with the option: .. option:: --help - --------- SEE ALSO -------- diff --git a/docs/source/bin/memflush.rst b/docs/source/bin/memflush.rst index 06a5d4d7..461ef85f 100644 --- a/docs/source/bin/memflush.rst +++ b/docs/source/bin/memflush.rst @@ -2,11 +2,8 @@ memflush - flush all data from a server ======================================= - Reset a server or list of servers - --------- SYNOPSIS -------- @@ -14,20 +11,15 @@ memflush [options] .. program:: memflush ------------ DESCRIPTION ----------- - :program:`memflush` resets the contents of memcached(1) servers. This means that all data in the specified servers will be deleted. - -------- OPTIONS ------- - You can specify servers via the option: .. option:: --servers @@ -40,9 +32,6 @@ For a full list of operations run the tool with option: .. option:: --help - - --------- SEE ALSO -------- diff --git a/docs/source/bin/memparse.rst b/docs/source/bin/memparse.rst index 926a97b5..4ad1b754 100644 --- a/docs/source/bin/memparse.rst +++ b/docs/source/bin/memparse.rst @@ -2,11 +2,8 @@ memparse - Parse an option string ================================= - Used to validate an option string - --------- SYNOPSIS -------- @@ -14,15 +11,11 @@ memparse [options] "option string" .. program:: memparse - ------------ DESCRIPTION ----------- - :program:`memparse` can be used to validate an option string. -------- OPTIONS ------- @@ -30,9 +23,6 @@ For a full list of operations run the tool with the option: .. option:: --help - - --------- SEE ALSO -------- diff --git a/docs/source/bin/memping.rst b/docs/source/bin/memping.rst index 5fdfef70..1239042e 100644 --- a/docs/source/bin/memping.rst +++ b/docs/source/bin/memping.rst @@ -2,8 +2,6 @@ memping - Test to see if a server is available. =============================================== - --------- SYNOPSIS -------- @@ -11,19 +9,14 @@ memping [options] [server] .. program:: memping - ------------ DESCRIPTION ----------- - :program:`memping` can be used to ping a memcached server to see if it is taking connections. -------- OPTIONS ------- - You can specify servers via the option: .. option:: --servers @@ -38,8 +31,6 @@ For a full list of operations run the tool with the option: .. option:: --help - --------- SEE ALSO -------- diff --git a/docs/source/bin/memrm.rst b/docs/source/bin/memrm.rst index 783961b4..d76aa347 100644 --- a/docs/source/bin/memrm.rst +++ b/docs/source/bin/memrm.rst @@ -2,11 +2,8 @@ memrm - Remove data from a server ================================= - memrm - Remove a key(s) from a collection of memcached servers - --------- SYNOPSIS -------- @@ -14,20 +11,14 @@ memrm [options] [key] .. program:: memrm - ------------ DESCRIPTION ----------- - :program:`memrm` removes items, specified by key, from memcached(1) servers. - -------- OPTIONS ------- - You can specify servers via the option: .. option:: --servers @@ -40,10 +31,6 @@ For a full list of operations run the tool with the .. option:: --help - - - --------- SEE ALSO -------- diff --git a/docs/source/bin/memslap.rst b/docs/source/bin/memslap.rst index 80ac2526..f0520062 100644 --- a/docs/source/bin/memslap.rst +++ b/docs/source/bin/memslap.rst @@ -2,8 +2,6 @@ memslap - Load testing and benchmarking a server ================================================= - --------- SYNOPSIS -------- @@ -11,23 +9,18 @@ memslap [options] .. program:: memslap ------------ DESCRIPTION ----------- - :program:`memslap` is a load generation and benchmark tool for memcached(1) servers. It generates configurable workload such as threads, concurrencies, connections, run time, overwrite, miss rate, key size, value size, get/set proportion, expected throughput, and so on. - -------- OPTIONS ------- - You can specify servers via the option: -.. option:: --servers +.. option:: --servers or via the environment variable: @@ -37,9 +30,6 @@ For a full list of operations run the tool with: .. option:: --help - - --------- SEE ALSO -------- diff --git a/docs/source/bin/memstat.rst b/docs/source/bin/memstat.rst index e3193de9..a6cc4ba9 100644 --- a/docs/source/bin/memstat.rst +++ b/docs/source/bin/memstat.rst @@ -2,11 +2,8 @@ memstat - Gather statistics from a server ========================================= - memstat - Display the operating status of a single or group of memcached servers - --------- SYNOPSIS -------- @@ -14,23 +11,18 @@ memstat [options] .. program:: memstat ------------ DESCRIPTION ----------- - :program:`memstat` dumps the state of memcached(1) servers. It displays all data to stdout. - -------- OPTIONS ------- - You can specify servers via the option: -.. option:: --servers +.. option:: --servers or via the environment variable: @@ -42,10 +34,8 @@ For a full list of operations run the tool with: .. option:: --help -.. option:: --analyze +.. option:: --analyze - --------- SEE ALSO -------- diff --git a/docs/source/bin/memtouch.rst b/docs/source/bin/memtouch.rst index 50e92415..c06d42e9 100644 --- a/docs/source/bin/memtouch.rst +++ b/docs/source/bin/memtouch.rst @@ -2,8 +2,6 @@ memtouch - Touches a key. ========================= - --------- SYNOPSIS -------- @@ -11,19 +9,14 @@ memtouch [options] key .. program:: memtouch - ------------ DESCRIPTION ----------- - :program:`memtouch` does a "touch" on the specified key. -------- OPTIONS ------- - You can specify servers via the option: .. option:: --servers @@ -38,9 +31,6 @@ For a full list of operations run the tool with the option: .. option:: --help - - --------- SEE ALSO -------- diff --git a/docs/source/index.rst b/docs/source/index.rst index fd4ebb9b..ab3e4e75 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -16,7 +16,6 @@ memory usage, thread safe, and provide full access to server side methods. libmemcached/index libmemcached/index_misc - .. toctree:: :titlesonly: :caption: libmemcachedutil diff --git a/docs/source/libhashkit/hashkit_create.rst b/docs/source/libhashkit/hashkit_create.rst index b11f6420..630ee0a4 100644 --- a/docs/source/libhashkit/hashkit_create.rst +++ b/docs/source/libhashkit/hashkit_create.rst @@ -34,13 +34,13 @@ the settings of the ptr hashkit object. The :func:`hashkit_free` frees any resources being consumed by the hashkit objects that were initialized with :func:`hashkit_create` or :func:`hashkit_clone`. -The :func:`hashkit_is_allocated` reports where the memory was allocated +The :func:`hashkit_is_allocated` reports where the memory was allocated for a hashkit object. RETURN VALUE ------------ -:func:`hashkit_create` and :func:`hashkit_clone` will return NULL on +:func:`hashkit_create` and :func:`hashkit_clone` will return NULL on failure or non-NULL on success. :func:`hashkit_is_allocated` returns true if the memory for the hashkit diff --git a/docs/source/libhashkit/hashkit_function.rst b/docs/source/libhashkit/hashkit_function.rst index d98dedac..f238d5db 100644 --- a/docs/source/libhashkit/hashkit_function.rst +++ b/docs/source/libhashkit/hashkit_function.rst @@ -31,7 +31,6 @@ DESCRIPTION These functions are used to set and retrieve the key and distribution hash functions. - RETURN VALUE ------------ diff --git a/docs/source/libmemcached.rst b/docs/source/libmemcached.rst index b0740adc..4f85d96c 100644 --- a/docs/source/libmemcached.rst +++ b/docs/source/libmemcached.rst @@ -56,7 +56,7 @@ Objects are stored on servers by hashing keys. The hash value maps the key to a particular server. All clients understand how this hashing works, so it is possibly to reliably both push data to a server and retrieve data from a server. -Group keys can be optionally used to group sets of objects with servers. +Group keys can be optionally used to group sets of objects with servers. Namespaces are supported, and can be used to partition caches so that multiple applications can use the same memcached servers. @@ -150,7 +150,6 @@ UTILITY LIBRARIES * :doc:`libhashkit` * :doc:`libmemcachedutil` - SEE ALSO -------- diff --git a/docs/source/libmemcached/memcached_analyze.rst b/docs/source/libmemcached/memcached_analyze.rst index 90189d96..9caeafa4 100644 --- a/docs/source/libmemcached/memcached_analyze.rst +++ b/docs/source/libmemcached/memcached_analyze.rst @@ -27,18 +27,18 @@ DESCRIPTION collection of servers) for their current state. Queries to find state return a :type:`memcached_analysis_st` structure. You are responsible for freeing this structure. -:func:`memcached_analyze` analyzes useful information based on the +:func:`memcached_analyze` analyzes useful information based on the provided servers and sets the result to the :type:`memcached_analysis_st` structure. The return value must be freed by the calling application. -A command line tool, :program:`memstat` with the option :option:`memstat --analyze`, +A command line tool, :program:`memstat` with the option :option:`memstat --analyze`, is provided so that you do not have to write an application to use this method. ------ RETURN ------ -A pointer to the allocated :type:`memcached_analysis_st` structure on +A pointer to the allocated :type:`memcached_analysis_st` structure on success and a NULL pointer on failure. You may inspect the error detail by checking the :type:`memcached_return_t` value. diff --git a/docs/source/libmemcached/memcached_append.rst b/docs/source/libmemcached/memcached_append.rst index dfd75062..ba3aaaab 100644 --- a/docs/source/libmemcached/memcached_append.rst +++ b/docs/source/libmemcached/memcached_append.rst @@ -6,14 +6,12 @@ Appending or Prepending to data on the server Appending or Prepending to data on the server - -------- SYNOPSIS -------- - #include - + .. function:: memcached_return_t memcached_prepend(memcached_st *ptr, const char *key, size_t key_length, const char *value, size_t value_length, time_t expiration, uint32_t flags) .. function:: memcached_return_t memcached_append(memcached_st *ptr, const char *key, size_t key_length, const char *value, size_t value_length, time_t expiration, uint32_t flags) @@ -24,13 +22,11 @@ SYNOPSIS Compile and link with -lmemcached - ----------- DESCRIPTION ----------- - -:func:`memcached_prepend` and memcached_append are used to +:func:`memcached_prepend` and memcached_append are used to modify information on a server. All methods take a key, and its length to store the object. Keys are currently limited to 250 characters when using either a version of memcached which is 1.4 or below, or when using the text @@ -40,13 +36,13 @@ meant to be used as a bitmap). "flags" is a 4byte space that is stored alongside of the main value. Many sub libraries make use of this field, so in most cases users should avoid making use of it. -:func:`memcached_prepend` places a segment of data before the last piece +:func:`memcached_prepend` places a segment of data before the last piece of data stored. Currently expiration and key are not used in the server. -:func:`memcached_append` places a segment of data at the end of the last +:func:`memcached_append` places a segment of data at the end of the last piece of data stored. Currently expiration and key are not used in the server. -:func:`memcached_prepend_by_key` and +:func:`memcached_prepend_by_key` and :func:`memcached_append_by_key` methods both behave in a similar method as the non key methods. The difference is that they use their group_key parameter to map objects to particular servers. @@ -73,23 +69,20 @@ there are at least 1318 bytes available to split among the key, key_prefix and value. If the total size of the command, including overhead, exceeds 1400 bytes, a `MEMCACHED_WRITE_FAILURE` will be returned. - ------ RETURN ------ - All methods return a value of type :type:`memcached_return_t`. On success the value will be `MEMCACHED_SUCCESS`. Use :func:`memcached_strerror` to translate this value to a printable string. - -------- SEE ALSO -------- .. only:: man - :manpage:`memcached(1)` :manpage:`libmemcached(3)` :manpage:`memcached_strerror(3)` :manpage:`memcached_set(3)` :manpage:`memcached_add(3)` :manpage:`memcached_cas(3)` :manpage:`memcached_replace(3)` +:manpage:`memcached(1)` :manpage:`libmemcached(3)` :manpage:`memcached_strerror(3)` :manpage:`memcached_set(3)` :manpage:`memcached_add(3)` :manpage:`memcached_cas(3)` :manpage:`memcached_replace(3)` diff --git a/docs/source/libmemcached/memcached_auto.rst b/docs/source/libmemcached/memcached_auto.rst index e4f27c51..61ffa124 100644 --- a/docs/source/libmemcached/memcached_auto.rst +++ b/docs/source/libmemcached/memcached_auto.rst @@ -9,7 +9,7 @@ SYNOPSIS -------- #include - + .. function:: memcached_return_t memcached_increment (memcached_st *ptr, const char *key, size_t key_length, uint32_t offset, uint64_t *value) .. function:: memcached_return_t memcached_decrement (memcached_st *ptr, const char *key, size_t key_length, uint32_t offset, uint64_t *value) @@ -28,12 +28,10 @@ SYNOPSIS Compile and link with -lmemcached - ----------- DESCRIPTION ----------- - :manpage:`memcached(1)` servers have the ability to increment and decrement keys (overflow and underflow are not detected). This gives you the ability to use memcached to generate shared sequences of values. @@ -70,7 +68,6 @@ when using the binary protocol. :func:`memcached_increment_with_initial_by_key`, and :func:`memcached_decrement_with_initial_by_key` are master key equivalents of the above. - ------ RETURN ------ @@ -80,7 +77,6 @@ A value of type :type:`memcached_return_t` is returned. On success that value will be `MEMCACHED_SUCCESS`. Use memcached_strerror to translate this value to a printable string. - -------- SEE ALSO -------- diff --git a/docs/source/libmemcached/memcached_cas.rst b/docs/source/libmemcached/memcached_cas.rst index da198ce9..1449196c 100644 --- a/docs/source/libmemcached/memcached_cas.rst +++ b/docs/source/libmemcached/memcached_cas.rst @@ -9,7 +9,6 @@ Working with data on the server in an atomic fashion SYNOPSIS -------- - #include .. function:: memcached_return_t memcached_cas(memcached_st *ptr, const char *key, size_t key_length, const char *value, size_t value_length, time_t expiration, uint32_t flags, uint64_t cas) @@ -18,19 +17,18 @@ SYNOPSIS Compile and link with -lmemcached - ----------- DESCRIPTION ----------- -:func:`memcached_cas` overwrites data in the server as long as the "cas" +:func:`memcached_cas` overwrites data in the server as long as the "cas" value is still the same in the server. You can get the cas value of a result by calling :func:`memcached_result_cas` on a memcached_result_st(3) structure. At the point that this note was written cas is still buggy in memcached. Turning on tests for it in libmemcached(3) is optional. Please see :func:`memcached_set` for information on how to do this. -:func:`memcached_cas_by_key` method behaves in a similar method as the non +:func:`memcached_cas_by_key` method behaves in a similar method as the non key methods. The difference is that it uses the group_key parameter to map objects to particular servers. @@ -49,18 +47,15 @@ non-cas ASCII set operations, there are at least 1335 bytes available to split among the key, key_prefix, and value; for cas ASCII operations there are at least 1318 bytes available to split among the key, key_prefix and value. If the total size of the command, including overhead, exceeds 1400 bytes, a `MEMCACHED_WRITE_FAILURE` will be returned. - ------ RETURN ------ - All methods return a value of type :type:`memcached_return_t`. On success the value will be `MEMCACHED_SUCCESS`. Use :func:`memcached_strerror` to translate this value to a printable string. - -------- SEE ALSO -------- diff --git a/docs/source/libmemcached/memcached_create.rst b/docs/source/libmemcached/memcached_create.rst index d416d25d..226b658e 100644 --- a/docs/source/libmemcached/memcached_create.rst +++ b/docs/source/libmemcached/memcached_create.rst @@ -11,40 +11,39 @@ SYNOPSIS .. type:: memcached_st .. function:: memcached_st* memcached_create(memcached_st *ptr) - + .. function:: void memcached_free(memcached_st *ptr) - + .. function:: memcached_st* memcached_clone(memcached_st *destination, memcached_st *source) - + .. function:: void memcached_servers_reset(memcached_st) Compile and link with -lmemcached - ----------- DESCRIPTION ----------- -:func:`memcached_create` is used to create a :type:`memcached_st` +:func:`memcached_create` is used to create a :type:`memcached_st` structure that will then be used by other libmemcached(3) functions to communicate with the server. You should either pass a statically declared :type:`memcached_st` to :func:`memcached_create` or a NULL. If a NULL passed in then a structure is allocated for you. -Please note, when you write new application use +Please note, when you write new application use :func:`memcached` over :func:`memcached_create`. -:func:`memcached_clone` is similar to :func:`memcached_create` but +:func:`memcached_clone` is similar to :func:`memcached_create` but it copies the defaults and list of servers from the source :type:`memcached_st`. If you pass a null as the argument for the source to clone, it is the same as a call to :func:`memcached_create`. If the destination argument is NULL a :type:`memcached_st` will be allocated for you. -:func:`memcached_servers_reset` allows you to zero out the list of +:func:`memcached_servers_reset` allows you to zero out the list of servers that the :type:`memcached_st` has. -To clean up memory associated with a :type:`memcached_st` structure you +To clean up memory associated with a :type:`memcached_st` structure you should pass it to :func:`memcached_free` when you are finished using it. :func:`memcached_free` is the only way to make sure all memory is deallocated when you finish using the structure. @@ -58,14 +57,12 @@ heap allocated structures. RETURN ------ - -:func:`memcached_create` returns a pointer to the :type:`memcached_st` +:func:`memcached_create` returns a pointer to the :type:`memcached_st` that was created (or initialized). On an allocation failure, it returns NULL. -:func:`memcached_clone` returns a pointer to the :type:`memcached_st` +:func:`memcached_clone` returns a pointer to the :type:`memcached_st` that was created (or initialized). On an allocation failure, it returns NULL. - -------- SEE ALSO -------- diff --git a/docs/source/libmemcached/memcached_delete.rst b/docs/source/libmemcached/memcached_delete.rst index 8c67e15d..767e01b4 100644 --- a/docs/source/libmemcached/memcached_delete.rst +++ b/docs/source/libmemcached/memcached_delete.rst @@ -1,28 +1,23 @@ -=========================== Deleting data from a server =========================== .. index:: object: memcached_st --------- SYNOPSIS -------- - #include - + .. function:: memcached_return_t memcached_delete (memcached_st *ptr, const char *key, size_t key_length, time_t expiration) .. function:: memcached_return_t memcached_delete_by_key (memcached_st *ptr, const char *group_key, size_t group_key_length, const char *key, size_t key_length, time_t expiration) Compile and link with -lmemcached ------------ DESCRIPTION ----------- - -:func:`memcached_delete` is used to delete a particular key. +:func:`memcached_delete` is used to delete a particular key. :func:`memcached_delete_by_key` works the same, but it takes a master key to find the given value. @@ -34,12 +29,9 @@ succeed, however). After the time passes, the item is finally deleted from serve Please note the the memcached server removed tests for expiration in the 1.4 version. - ------- RETURN ------ - A value of type :type:`memcached_return_t` is returned On success that value will be `MEMCACHED_SUCCESS`. Use :func:`memcached_strerror` to translate this value to a printable @@ -48,9 +40,6 @@ string. If you are using the non-blocking mode of the library, success only means that the message was queued for delivery. - - --------- SEE ALSO -------- diff --git a/docs/source/libmemcached/memcached_dump.rst b/docs/source/libmemcached/memcached_dump.rst index 077ca7e7..d8b5c9c5 100644 --- a/docs/source/libmemcached/memcached_dump.rst +++ b/docs/source/libmemcached/memcached_dump.rst @@ -2,52 +2,41 @@ Dumping data from a server ========================== - Get a list of keys found on memcached servers .. index:: object: memcached_st - -------- SYNOPSIS -------- - #include .. function:: memcached_return_t memcached_dump (memcached_st *ptr, memcached_dump_fn *function, void *context, uint32_t number_of_callbacks) - + .. type:: memcached_return_t (*memcached_dump_fn)(memcached_st *ptr, const char *key, size_t key_length, void *context) Compile and link with -lmemcached - - ----------- DESCRIPTION ----------- - -:func:`memcached_dump` is used to get a list of keys found in memcached(1) +:func:`memcached_dump` is used to get a list of keys found in memcached(1) servers. Because memcached(1) does not guarantee to dump all keys you can not assume you have fetched all keys from the server. The function takes an array of callbacks that it will use to execute on keys as they are found. Currently the binary protocol is not tested. - ------- RETURN ------ - A value of type :type:`memcached_return_t` is returned On success that value will be `MEMCACHED_SUCCESS`. Use :func:`memcached_strerror` to translate this value to a printable string. - - -------- SEE ALSO -------- diff --git a/docs/source/libmemcached/memcached_exist.rst b/docs/source/libmemcached/memcached_exist.rst index 84fca341..4e0706c2 100644 --- a/docs/source/libmemcached/memcached_exist.rst +++ b/docs/source/libmemcached/memcached_exist.rst @@ -8,9 +8,8 @@ Determine if a keys exists. SYNOPSIS -------- - #include - + .. function:: memcached_return_t memcached_exist(memcached_st *ptr, char *key, size_t *key_length) .. function:: memcached_return_t memcached_exist_by_key(memcached_st *ptr, char *group_key, size_t *group_key_length, char *key, size_t *key_length) @@ -19,14 +18,12 @@ Compile and link with -lmemcached .. versionadded:: 0.53 - ----------- DESCRIPTION ----------- :func:`memcached_exist()` can be used to check if a key exists. - ------ RETURN ------ diff --git a/docs/source/libmemcached/memcached_fetch.rst b/docs/source/libmemcached/memcached_fetch.rst index 4df61ab8..a7f438a9 100644 --- a/docs/source/libmemcached/memcached_fetch.rst +++ b/docs/source/libmemcached/memcached_fetch.rst @@ -8,9 +8,8 @@ memcached_fetch SYNOPSIS -------- - #include - + .. function:: char *memcached_fetch(memcached_st *ptr, char *key, size_t *key_length, size_t *value_length, uint32_t *flags, memcached_return_t *error) .. deprecated:: 0.50 @@ -18,30 +17,28 @@ SYNOPSIS Compile and link with -lmemcached - ----------- DESCRIPTION ----------- -:func:`memcached_fetch` is used to fetch an individual value from the server. :func:`memcached_mget` must always be called before using this method. +:func:`memcached_fetch` is used to fetch an individual value from the server. :func:`memcached_mget` must always be called before using this method. You must pass in a key and its length to fetch the object. You must supply three pointer variables which will give you the state of the returned object. A :type:`uint32_t` pointer to contain whatever flags you stored with the value, a :type:`size_t` pointer which will be filled with size of of the object, and a :type:`memcached_return_t` pointer to hold any error. The object will be returned upon success and NULL will be returned on failure. `MEMCACHED_END` is returned by the \*error value when all objects that have been found are returned. The final value upon `MEMCACHED_END` is null. -Values returned by :func:`memcached_fetch` must be freed by the caller. +Values returned by :func:`memcached_fetch` must be freed by the caller. -All of the above functions are not tested when the +All of the above functions are not tested when the `MEMCACHED_BEHAVIOR_USE_UDP` has been set. Executing any of these functions with this behavior on will result in `MEMCACHED_NOT_SUPPORTED` being returned, or for those functions which do not return a :type:`memcached_return_t`, the error function parameter will be set to `MEMCACHED_NOT_SUPPORTED`. - ------ RETURN ------ -:func:`memcached_fetch` sets error to +:func:`memcached_fetch` sets error to to `MEMCACHED_END` upon successful conclusion. `MEMCACHED_NOTFOUND` will be return if no keys at all were found. @@ -49,7 +46,6 @@ to `MEMCACHED_END` upon successful conclusion. and the key was set larger then `MEMCACHED_MAX_KEY`, which was the largest key allowed for the original memcached ascii server. - -------- SEE ALSO -------- diff --git a/docs/source/libmemcached/memcached_flush.rst b/docs/source/libmemcached/memcached_flush.rst index 661d8e6a..451e8e9f 100644 --- a/docs/source/libmemcached/memcached_flush.rst +++ b/docs/source/libmemcached/memcached_flush.rst @@ -6,24 +6,20 @@ Wiping clean the contents of a server Wipe contents of memcached servers - -------- SYNOPSIS -------- - #include - + .. function:: memcached_return_t memcached_flush (memcached_st *ptr, time_t expiration) Compile and link with -lmemcached - ----------- DESCRIPTION ----------- - :func::`memcached_flush` is used to wipe clean the contents of :program:`memcached` servers. It will either do this immediately or expire the content based on the expiration time passed to the method (a value of zero causes an immediate @@ -31,17 +27,13 @@ flush). The operation is not atomic to multiple servers, just atomic to a single server. That is, it will flush the servers in the order that they were added. - ------- RETURN ------ - -A value of type :type:`memcached_return_t` is returned +A value of type :type:`memcached_return_t` is returned On success that value will be `MEMCACHED_SUCCESS`. Use :type:`memcached_strerror` to translate this value to a printable string. - -------- SEE ALSO -------- diff --git a/docs/source/libmemcached/memcached_flush_buffers.rst b/docs/source/libmemcached/memcached_flush_buffers.rst index d94fa65d..d54da98a 100644 --- a/docs/source/libmemcached/memcached_flush_buffers.rst +++ b/docs/source/libmemcached/memcached_flush_buffers.rst @@ -2,7 +2,6 @@ Flushing client buffers ======================= - .. index:: object: memcached_st Flush and send buffered commands @@ -12,34 +11,27 @@ SYNOPSIS -------- #include - + .. function:: memcached_return_t memcached_flush_buffers (memcached_st *ptr) Compile and link with -lmemcached - ----------- DESCRIPTION ----------- - -:func:`memcached_flush_buffers` is used in conjunction with +:func:`memcached_flush_buffers` is used in conjunction with `MEMCACHED_BEHAVIOR_BUFFER_REQUESTS` (see memcached_behavior(3)) to flush all buffers by sending the buffered commands to the server for processing. - ------ RETURN ------ - A value of type :type:`memcached_return_t` is returned On success that value will be `MEMCACHED_SUCCESS`. Use :func:`memcached_strerror` to translate this value to a printable string. - - - -------- SEE ALSO -------- diff --git a/docs/source/libmemcached/memcached_generate_hash_value.rst b/docs/source/libmemcached/memcached_generate_hash_value.rst index 2e151a5c..9d8e00b3 100644 --- a/docs/source/libmemcached/memcached_generate_hash_value.rst +++ b/docs/source/libmemcached/memcached_generate_hash_value.rst @@ -6,16 +6,13 @@ Generating hash values directly Hash a key value - --------- SYNOPSIS -------- - #include .. type:: memcached_hash_t - + .. function:: uint32_t memcached_generate_hash_value (const char *key, size_t key_length, memcached_hash_t hash_algorithm) .. function:: uint32_t memcached_generate_hash (memcached_st *ptr, const char *key, size_t key_length) @@ -42,15 +39,12 @@ SYNOPSIS .. type:: MEMCACHED_HASH_MURMUR3 - Compile and link with -lmemcachedutil -lmemcached - ----------- DESCRIPTION ----------- - :func:`memcached_generate_hash_value` allows you to hash a key using one of the hash functions defined in the library. This method is provided for the convenience of higher-level language bindings and is not necessary @@ -66,18 +60,14 @@ defaults of :type:`memcached_st`. As of version 0.36 all hash methods have been placed into the library libhashkit(3) which is linked with libmemcached(3). For more information please see its documentation. - ------ RETURN ------ - A 32-bit integer which is the result of hashing the given key. For 64-bit hash algorithms, only the least-significant 32 bits are returned. - - -------- SEE ALSO -------- diff --git a/docs/source/libmemcached/memcached_get.rst b/docs/source/libmemcached/memcached_get.rst index 4149659f..0742b707 100644 --- a/docs/source/libmemcached/memcached_get.rst +++ b/docs/source/libmemcached/memcached_get.rst @@ -8,9 +8,8 @@ Retrieving data from the server SYNOPSIS -------- - #include - + .. function:: memcached_result_st * memcached_fetch_result (memcached_st *ptr, memcached_result_st *result, memcached_return_t *error) .. function:: char * memcached_get (memcached_st *ptr, const char *key, size_t key_length, size_t *value_length, uint32_t *flags, memcached_return_t *error) @@ -31,13 +30,11 @@ SYNOPSIS Compile and link with -lmemcached - ----------- DESCRIPTION ----------- - -:func:`memcached_get` is used to fetch an individual value from the server. +:func:`memcached_get` is used to fetch an individual value from the server. You must pass in a key and its length to fetch the object. You must supply three pointer variables which will give you the state of the returned object. A :type:`uint32_t` pointer to contain whatever flags you stored with the value, a :type:`size_t` pointer which will be filled with size of of @@ -46,7 +43,7 @@ object will be returned upon success and NULL will be returned on failure. Any object returned by :func:`memcached_get` must be released by the caller application. -:func:`memcached_mget` is used to select multiple keys at once. For +:func:`memcached_mget` is used to select multiple keys at once. For multiple key operations it is always faster to use this function. This function always works asynchronously. To retrieve data after a successful execution of :func:`memcached_mget`, you will need to @@ -54,19 +51,19 @@ call :func:`memcached_fetch_result`. You should continue to call this function it returns a NULL (i.e. no more values). If you need to quit in the middle of a :func:`memcached_mget` call, you can execute a :func:`memcached_quit`, those this is not required. -:func:`memcached_fetch_result` is used to fetch an individual value from the server. :func:`memcached_mget` must always be called before using this method. +:func:`memcached_fetch_result` is used to fetch an individual value from the server. :func:`memcached_mget` must always be called before using this method. You must pass in a key and its length to fetch the object. You must supply three pointer variables which will give you the state of the returned object. A :type:`uint32_t` pointer to contain whatever flags you stored with the value, a :type:`size_t` pointer which will be filled with size of of the object, and a :type:`memcached_return_t` pointer to hold any error. The object will be returned upon success and NULL will be returned on failure. `MEMCACHED_END` is returned by the \*error value when all objects that have been found are returned. The final value upon `MEMCACHED_END` is null. -:func:`memcached_fetch_result` is used to return a :type:`memcached_result_st` structure from a memcached server. The result object is forward compatible +:func:`memcached_fetch_result` is used to return a :type:`memcached_result_st` structure from a memcached server. The result object is forward compatible with changes to the server. For more information please refer to the :type:`memcached_result_st` help. This function will dynamically allocate a result structure for you if you do not pass one to the function. -:func:`memcached_fetch_execute` is a callback function for result sets. +:func:`memcached_fetch_execute` is a callback function for result sets. Instead of returning the results to you for processing, it passes each of the result sets to the list of functions you provide. It passes to the function a :type:`memcached_st` that can be cloned for use in the called @@ -86,24 +83,21 @@ solves this problem by processing some of the results before continuing sending out requests. Please note that this function is only available in the binary protocol. -:func:`memcached_get_by_key` and :func:`memcached_mget_by_key` behave +:func:`memcached_get_by_key` and :func:`memcached_mget_by_key` behave in a similar nature as :func:`memcached_get` and :func:`memcached_mget`. The difference is that they take a master key that is used for determining which server an object was stored if key partitioning was used for storage. -All of the above functions are not tested when the +All of the above functions are not tested when the `MEMCACHED_BEHAVIOR_USE_UDP` has been set. Executing any of these functions with this behavior on will result in `MEMCACHED_NOT_SUPPORTED` being returned, or for those functions which do not return a :type:`memcached_return_t`, the error function parameter will be set to `MEMCACHED_NOT_SUPPORTED`. - ------- RETURN ------ - All objects retrieved via :func:`memcached_get` or :func:`memcached_get_by_key` must be freed with :manpage:`free(3)`. -:func:`memcached_get` will return NULL on +:func:`memcached_get` will return NULL on error. You must look at the value of error to determine what the actual error was. @@ -115,7 +109,6 @@ keys at all were found. to `MEMCACHED_END` upon successful conclusion. `MEMCACHED_NOTFOUND` will be return if no keys at all were found. - -------- SEE ALSO -------- diff --git a/docs/source/libmemcached/memcached_last_error.rst b/docs/source/libmemcached/memcached_last_error.rst index 9b82c387..c5ddf490 100644 --- a/docs/source/libmemcached/memcached_last_error.rst +++ b/docs/source/libmemcached/memcached_last_error.rst @@ -8,7 +8,7 @@ SYNOPSIS Compile and link with -lmemcached .. function:: memcached_return_t memcached_last_error(const memcached_st *) - + .. function:: const char *memcached_last_error_message(const memcached_st *) .. function:: int memcached_last_error_errno(const memcached_st *) @@ -31,7 +31,6 @@ need to be de-allocated. NULL will be returned if no error has occurred. `memcached_last_error_errno` returns any last local error code obtained from :manpage:`errno(3)`. - SEE ALSO -------- diff --git a/docs/source/libmemcached/memcached_memory_allocators.rst b/docs/source/libmemcached/memcached_memory_allocators.rst index 230accb7..7cd89122 100644 --- a/docs/source/libmemcached/memcached_memory_allocators.rst +++ b/docs/source/libmemcached/memcached_memory_allocators.rst @@ -10,7 +10,6 @@ Manage memory allocator functions SYNOPSIS -------- - #include .. function:: memcached_return_t memcached_set_memory_allocators (memcached_st *ptr, memcached_malloc_fn mem_malloc, memcached_free_fn mem_free, memcached_realloc_fn mem_realloc, memcached_calloc_fn mem_calloc, void *context) @@ -29,54 +28,46 @@ SYNOPSIS Compile and link with -lmemcached - - ----------- DESCRIPTION ----------- - libmemcached(3) allows you to specify your own memory allocators, optimized for your application. This enables libmemcached to be used inside of applications that have their own malloc implementation. -:func:`memcached_set_memory_allocators` is used to set the memory +:func:`memcached_set_memory_allocators` is used to set the memory allocators used by the memcached instance specified by ptr. Please note that you cannot override only one of the memory allocators, you have to specify a complete new set if you want to override one of them. All of the memory allocation functions should behave as specified in the C99 standard. Specify NULL as all functions to reset them to the default values. -:func:`memcached_get_memory_allocators` is used to get the currently used +:func:`memcached_get_memory_allocators` is used to get the currently used memory allocators by a memcached handle. -:func:`memcached_get_memory_allocators_context` returns the void \* that +:func:`memcached_get_memory_allocators_context` returns the void \* that was passed in during the call to :func:`memcached_set_memory_allocators`. The first argument to the memory allocator functions is a pointer to a memcached structure, the is passed as const and you will need to clone it in order to make use of any operation which would modify it. - ----- NOTES ----- - In version 0.38 all functions were modified to have a context void pointer passed to them. This was so that customer allocators could have their own space for memory. - ------ RETURN ------ - -:func:`memcached_set_memory_allocators` return `MEMCACHED_SUCCESS` +:func:`memcached_set_memory_allocators` return `MEMCACHED_SUCCESS` upon success, and `MEMCACHED_FAILURE` if you don't pass a complete set of function pointers. - -------- SEE ALSO -------- diff --git a/docs/source/libmemcached/memcached_quit.rst b/docs/source/libmemcached/memcached_quit.rst index c852a2a1..a50046d3 100644 --- a/docs/source/libmemcached/memcached_quit.rst +++ b/docs/source/libmemcached/memcached_quit.rst @@ -9,7 +9,7 @@ SYNOPSIS -------- #include - + .. function:: void memcached_quit (memcached_st *ptr) Compile and link with -lmemcached @@ -18,8 +18,7 @@ Compile and link with -lmemcached DESCRIPTION ----------- - -:func:`memcached_quit` will disconnect you from all currently connected +:func:`memcached_quit` will disconnect you from all currently connected servers. It will also reset the state of the connection (ie, any :func:`memcached_fetch` you are in the middle of will be terminated). This function is called automatically when you call :func:`memcached_free` on the :type:`memcached_st` structure. @@ -28,17 +27,14 @@ hashes and parameters will handle connections to the server for you. This function is provided mainly so that you can timeout your connections or reset connections during the middle of a :func:`memcached_fetch`. - ------ RETURN ------ - A value of type :type:`memcached_return_t` is returned On success that value will be `MEMCACHED_SUCCESS`. Use :func:`memcached_strerror` to translate this value to a printable string. - -------- SEE ALSO -------- diff --git a/docs/source/libmemcached/memcached_result_st.rst b/docs/source/libmemcached/memcached_result_st.rst index c0080b29..76c80d02 100644 --- a/docs/source/libmemcached/memcached_result_st.rst +++ b/docs/source/libmemcached/memcached_result_st.rst @@ -36,14 +36,11 @@ SYNOPSIS Compile and link with -lmemcachedutil -lmemcached - - ----------- DESCRIPTION ----------- - -libmemcached(3) can optionally return a :type:`memcached_result_st` which +libmemcached(3) can optionally return a :type:`memcached_result_st` which acts as a result object. The result objects have added benefits over the character pointer returns, in that they are forward compatible with new return items that future memcached servers may implement (the best current @@ -63,7 +60,7 @@ structure. If the structure was also allocated, it will deallocate it. :func:`memcached_result_key_value` returns the key value associated with the current result object. -:func:`memcached_result_key_length` returns the key length associated with +:func:`memcached_result_key_length` returns the key length associated with the current result object. :func:`memcached_result_value` returns the result value associated with the @@ -74,7 +71,7 @@ associated with the current result object. You must call free() to release this value, unless you have made use of a custom allocator. Use of a custom allocator requires that you create your own custom free() to release it. -:func:`memcached_result_length` returns the result length associated with +:func:`memcached_result_length` returns the result length associated with the current result object. :func:`memcached_result_flags` returns the flags associated with the @@ -98,18 +95,14 @@ You may wish to avoid using memcached_result_create(3) with a stack based allocation. The most common issues related to ABI safety involve heap allocated structures. - ------ RETURN ------ - Varies, see particular functions. All structures must have :func:`memcached_result_free` called on them for cleanup purposes. Failure to do this will result in leaked memory. - - -------- SEE ALSO -------- diff --git a/docs/source/libmemcached/memcached_sasl.rst b/docs/source/libmemcached/memcached_sasl.rst index 6b1a0121..26b00387 100644 --- a/docs/source/libmemcached/memcached_sasl.rst +++ b/docs/source/libmemcached/memcached_sasl.rst @@ -4,7 +4,6 @@ SASL support .. index:: object: memcached_st - -------- SYNOPSIS -------- @@ -21,13 +20,10 @@ SYNOPSIS Compile and link with -lmemcached - - ----------- DESCRIPTION ----------- - libmemcached(3) allows you to plug in your own callbacks function used by libsasl to perform SASL authentication. @@ -42,18 +38,14 @@ in memory. If you choose to use this method you have to call :type:`memcached_destroy_sasl_auth_data` if you specify your own callback function with :func:`memcached_set_sasl_callbacks`. - ------ RETURN ------ - :func:`memcached_get_sasl_callbacks` returns the callbacks currently used by this memcached handle. :func:`memcached_set_sasl_auth_data` returns `MEMCACHED_SUCCESS` upon success. - - -------- SEE ALSO -------- diff --git a/docs/source/libmemcached/memcached_server_st.rst b/docs/source/libmemcached/memcached_server_st.rst index 111a829a..9cc23929 100644 --- a/docs/source/libmemcached/memcached_server_st.rst +++ b/docs/source/libmemcached/memcached_server_st.rst @@ -16,13 +16,13 @@ SYNOPSIS .. function:: const memcached_instance_st * memcached_server_list (memcached_st *ptr) .. function:: void memcached_server_list_free (memcached_server_list_st list) - + .. function:: memcached_server_list_st memcached_server_list_append (memcached_server_list_st list, const char *hostname, in_port_t port, memcached_return_t *error) - + .. function:: uint32_t memcached_server_list_count (memcached_server_list_st list) - + .. function:: const char *memcached_server_error (const memcached_instance_st * instance) - + .. function:: void memcached_server_error_reset (const memcached_instance_st * list) .. deprecated:: 0.39 diff --git a/docs/source/libmemcached/memcached_servers.rst b/docs/source/libmemcached/memcached_servers.rst index 4c926da4..a1286a7e 100644 --- a/docs/source/libmemcached/memcached_servers.rst +++ b/docs/source/libmemcached/memcached_servers.rst @@ -2,12 +2,11 @@ Manipulate the server information stored in memcached_st ======================================================== --------- SYNOPSIS -------- #include - + .. type:: memcached_server_fn .. function:: uint32_t memcached_server_count (memcached_st *ptr) @@ -18,7 +17,7 @@ SYNOPSIS .. function:: memcached_return_t memcached_server_add_unix_socket (memcached_st *ptr, const char *socket) -.. function:: memcached_return_t memcached_server_push (memcached_st *ptr, const memcached_server_st *list) +.. function:: memcached_return_t memcached_server_push (memcached_st *ptr, const memcached_server_st *list) .. function:: const memcached_instance_st * memcached_server_by_key (memcached_st *ptr, const char *key, size_t key_length, memcached_return_t *error) @@ -28,13 +27,9 @@ SYNOPSIS compile and link with -lmemcached - - ------------ DESCRIPTION ----------- - `libmemcached` performs operations on a list of hosts. The order of these hosts determine routing to keys. Functions are provided to add keys to memcached_st structures. To manipulate lists of servers see @@ -46,7 +41,7 @@ servers being used by a :type:`memcached_st` structure. :func:`memcached_server_add` pushes a single TCP server into the :type:`memcached_st` structure. This server will be placed at the end. Duplicate servers are allowed, so duplication is not checked. Executing this function with the `MEMCACHED_BEHAVIOR_USE_UDP` behavior set will result in a `MEMCACHED_INVALID_HOST_PROTOCOL`. -:func:`memcached_server_add_udp` pushes a single UDP server into the :type:`memcached_st` structure. This server will be placed at the end. Duplicate +:func:`memcached_server_add_udp` pushes a single UDP server into the :type:`memcached_st` structure. This server will be placed at the end. Duplicate servers are allowed, so duplication is not checked. Executing this function with out setting the `MEMCACHED_BEHAVIOR_USE_UDP` behavior will result in a `MEMCACHED_INVALID_HOST_PROTOCOL`. @@ -54,7 +49,7 @@ servers are allowed, so duplication is not checked. Executing this function with Duplicate servers are allowed, so duplication is not checked. The length of the filename must be one character less than `MEMCACHED_MAX_HOST_LENGTH`. -:func:`memcached_server_push` pushes an array of :type:`memcached_server_st` into the :type:`memcached_st` structure. These servers will be placed at +:func:`memcached_server_push` pushes an array of :type:`memcached_server_st` into the :type:`memcached_st` structure. These servers will be placed at the end. Duplicate servers are allowed, so duplication is not checked. A copy is made of structure so the list provided (and any operations on the list) are not saved. @@ -62,26 +57,23 @@ the list) are not saved. :func:`memcached_server_by_key` allows you to provide a key and retrieve the server which would be used for assignment. -:func:`memcached_server_get_last_disconnect` returns a pointer to the last +:func:`memcached_server_get_last_disconnect` returns a pointer to the last server for which there was a connection problem. It does not mean this particular server is currently dead but if the library is reporting a server is, the returned server is a very good candidate. -:func:`memcached_server_cursor` takes a memcached_st and loops through the +:func:`memcached_server_cursor` takes a memcached_st and loops through the list of hosts currently in the cursor calling the list of callback functions provided. You can optionally pass in a value via context which will be provided to each callback function. An error return from any callback will terminate the loop. :func:`memcached_server_cursor` is passed the original caller :type:`memcached_st` in its current state. - ------ RETURN ------ - Varies, see particular functions. - -------- SEE ALSO -------- diff --git a/docs/source/libmemcached/memcached_set.rst b/docs/source/libmemcached/memcached_set.rst index dc044d59..e199427b 100644 --- a/docs/source/libmemcached/memcached_set.rst +++ b/docs/source/libmemcached/memcached_set.rst @@ -31,7 +31,7 @@ store the object. Keys are currently limited to 250 characters by the memcached(1) server. You must supply both a value and a length. Optionally you may test an expiration time for the object and a 16 byte value (it is meant to be used as a bitmap). "flags" is a 4byte space that is stored alongside of the main value. Many sub libraries make use of this field, so in most cases users should avoid making use of it. -:func:`memcached_set` will write an object to the server. If an object +:func:`memcached_set` will write an object to the server. If an object already exists it will overwrite what is in the server. If the object does not exist it will be written. If you are using the non-blocking mode this function will always return true unless a network error occurs. diff --git a/docs/source/libmemcached/memcached_set_encoding_key.rst b/docs/source/libmemcached/memcached_set_encoding_key.rst index d8b15a87..467eb669 100644 --- a/docs/source/libmemcached/memcached_set_encoding_key.rst +++ b/docs/source/libmemcached/memcached_set_encoding_key.rst @@ -9,7 +9,7 @@ SYNOPSIS -------- #include - + .. function:: void memcached_set_encoding_key (memcached_st *ptr, const char *string, const size_t string_length) Compile and link with -lmemcached @@ -18,23 +18,17 @@ Compile and link with -lmemcached DESCRIPTION ----------- - :func:`memcached_set_encoding_key` sets the key that will be used to encrypt and decrypt data as it is sent and received from the server. Currently only AES is is supported. - ------- RETURN ------ - A value of type :type:`memcached_return_t` is returned On success that value will be `MEMCACHED_SUCCESS`. Use :func:`memcached_strerror` to translate this value to a printable string. - - -------- SEE ALSO -------- diff --git a/docs/source/libmemcached/memcached_stats.rst b/docs/source/libmemcached/memcached_stats.rst index 8df17de0..a6852982 100644 --- a/docs/source/libmemcached/memcached_stats.rst +++ b/docs/source/libmemcached/memcached_stats.rst @@ -2,12 +2,10 @@ Working with statistical information from a server ================================================== - Get memcached statistics .. index:: object: memcached_st - -------- SYNOPSIS -------- @@ -34,7 +32,6 @@ Compile and link with -lmemcached DESCRIPTION ----------- - libmemcached(3) has the ability to query a memcached server (or collection of servers) for their current state. Queries to find state return a :type:`memcached_stat_st` structure. You are responsible for freeing this structure. While it is possible to access the structure directly it is not advisable. :func:`memcached_stat_get_value` has been provided to query the structure. @@ -55,19 +52,15 @@ obtain information on. A command line tool, memstat(1), is provided so that you do not have to write an application to do this. - ------ RETURN ------ - Varies, see particular functions. Any method returning a :type:`memcached_stat_st` expects you to free the memory allocated for it. - - -------- SEE ALSO -------- diff --git a/docs/source/libmemcached/memcached_touch.rst b/docs/source/libmemcached/memcached_touch.rst index 1b92e6ef..0e00264e 100644 --- a/docs/source/libmemcached/memcached_touch.rst +++ b/docs/source/libmemcached/memcached_touch.rst @@ -8,9 +8,8 @@ memcached_touch, memcached_touch_by_key SYNOPSIS -------- - #include - + .. function:: memcached_return_t memcached_touch (memcached_st *ptr, const char *key, size_t key_length, time_t expiration) .. function:: memcached_return_t memcached_touch_by_key (memcached_st *ptr, const char *group_key, size_t group_key_length, const char *key, size_t key_length, time_t expiration) @@ -21,24 +20,19 @@ Compile and link with -lmemcached DESCRIPTION ----------- - :func:`memcached_touch` is used to update the expiration time on an existing key. :func:`memcached_touch_by_key` works the same, but it takes a master key to find the given value. - ------ RETURN ------ - A value of type :type:`memcached_return_t` is returned On success that value will be `MEMCACHED_SUCCESS`. Use :func:`memcached_strerror` to translate this value to a printable string. - - -------- SEE ALSO -------- diff --git a/docs/source/libmemcached/memcached_user_data.rst b/docs/source/libmemcached/memcached_user_data.rst index 9f62f890..06512244 100644 --- a/docs/source/libmemcached/memcached_user_data.rst +++ b/docs/source/libmemcached/memcached_user_data.rst @@ -6,20 +6,16 @@ Storing custom user information in the client. Manage user specific data - ------- LIBRARY ------- - C Client Library for memcached (libmemcached, -lmemcached) - -------- SYNOPSIS -------- - #include .. function:: void *memcached_get_user_data (memcached_st *ptr) @@ -28,13 +24,10 @@ SYNOPSIS Compile and link with -lmemcached - - ----------- DESCRIPTION ----------- - libmemcached(3) allows you to store a pointer to a user specific data inside the memcached_st structure. @@ -43,18 +36,14 @@ the memcached_st structure. :func:`memcached_get_user_data` is used to retrieve the user specific data in the :type:`memcached_st` structure. - ------ RETURN ------ - :func:`memcached_set_user_data` returns the previous value of the user specific data. :func:`memcached_get_user_data` returns the current value uf the user specific data. - - -------- SEE ALSO -------- diff --git a/docs/source/libmemcached/memcached_verbosity.rst b/docs/source/libmemcached/memcached_verbosity.rst index e134bb27..ed76a90d 100644 --- a/docs/source/libmemcached/memcached_verbosity.rst +++ b/docs/source/libmemcached/memcached_verbosity.rst @@ -16,28 +16,23 @@ SYNOPSIS Compile and link with -lmemcached - ----------- DESCRIPTION ----------- - :func:`memcached_verbosity` modifies the "verbosity" of the memcached(1) servers referenced in the :type:`memcached_st` parameter. - ------ RETURN ------ - A value of type :type:`memcached_return_t` is returned. On success that value will be `MEMCACHED_SUCCESS`. Use :func:`memcached_strerror` to translate this value to a printable string. - -------- SEE ALSO -------- diff --git a/docs/source/libmemcached/memcached_version.rst b/docs/source/libmemcached/memcached_version.rst index a5825fab..40c41b70 100644 --- a/docs/source/libmemcached/memcached_version.rst +++ b/docs/source/libmemcached/memcached_version.rst @@ -2,51 +2,42 @@ Getting version information about the client and server ======================================================= - -------- SYNOPSIS -------- #include -.. function:: const char * memcached_lib_version (void) +.. function:: const char * memcached_lib_version (void) .. function:: memcached_return_t memcached_version (memcached_st *ptr) - Compile and link with -lmemcached - - ----------- DESCRIPTION ----------- - :func:`memcached_lib_version` is used to return a simple version string representing the libmemcached version (client library version, not server version) :func:`memcached_version` is used to set the major, minor, and micro versions of each memcached server being used by the memcached_st connection structure. It returns the memcached server return code. - ------ RETURN ------ - :func:`memcached_lib_version` returns a string with the version of the libmemcached driver. A value of :type:`memcached_return_t` is returned from :func:'memcached_version' -On success that value will be `MEMCACHED_SUCCESS`. +On success that value will be `MEMCACHED_SUCCESS`. If called with the `MEMCACHED_BEHAVIOR_USE_UDP` behavior set, the value `MEMCACHED_NOT_SUPPORTED` will be returned. -Use :func:`memcached_strerror` to translate this value to +Use :func:`memcached_strerror` to translate this value to a printable string. - - -------- SEE ALSO -------- diff --git a/docs/source/libmemcachedutil/memcached_pool.rst b/docs/source/libmemcachedutil/memcached_pool.rst index 5417f1af..0da28203 100644 --- a/docs/source/libmemcachedutil/memcached_pool.rst +++ b/docs/source/libmemcachedutil/memcached_pool.rst @@ -1,8 +1,6 @@ -============================ Working with memcached pools ============================ --------- SYNOPSIS -------- @@ -11,10 +9,10 @@ SYNOPSIS .. type:: struct memcached_pool_st memcached_pool_st -.. function:: memcached_pool_st* memcached_pool(const char *option_string, size_t option_string_length) +.. function:: memcached_pool_st* memcached_pool(const char *option_string, size_t option_string_length) .. function:: memcached_st* memcached_pool_destroy(memcached_pool_st* pool) - + .. function:: memcached_st* memcached_pool_fetch(memcached_pool_st*, struct timespec* relative_time, memcached_return_t* rc) .. versionadded:: 0.53 Synonym for memcached_pool_pop @@ -22,11 +20,10 @@ SYNOPSIS .. function:: memcached_return_t memcached_pool_release(memcached_pool_st* pool, memcached_st* mmc) .. versionadded:: 0.53 Synonym for memcached_pool_push. - + .. function:: memcached_return_t memcached_pool_behavior_set(memcached_pool_st *pool, memcached_behavior_t flag, uint64_t data) - -.. function:: memcached_return_t memcached_pool_behavior_get(memcached_pool_st *pool, memcached_behavior_t flag, uint64_t *value) +.. function:: memcached_return_t memcached_pool_behavior_get(memcached_pool_st *pool, memcached_behavior_t flag, uint64_t *value) .. function:: memcached_pool_st* memcached_pool_create(memcached_st* mmc, int initial, int max) .. deprecated:: 0.46 @@ -40,13 +37,10 @@ SYNOPSIS .. deprecated:: 0.53 Use :func:`memcached_pool_release` - ------------ DESCRIPTION ----------- - -:func:`memcached_pool` is used to create a connection pool of objects you +:func:`memcached_pool` is used to create a connection pool of objects you may use to remove the overhead of using memcached_clone for short lived :type:`memcached_st` objects. Please see :doc:`../libmemcached/configuration` for details on the format of the configuration string. @@ -72,7 +66,6 @@ is used to get/set behavior flags on all connections in the pool. Both :func:`memcached_pool_release` and :func:`memcached_pool_fetch` are thread safe. ------- RETURN ------ @@ -96,9 +89,6 @@ memcached_pool_fetch may return MEMCACHED_TIMEOUT if a timeout occurs while waiting for a free memcached_st. MEMCACHED_NOTFOUND if no memcached_st was available. - - --------- SEE ALSO -------- -- 2.30.2