From: Brian Aker Date: Sat, 25 Jun 2011 00:21:37 +0000 (-0700) Subject: Update docs. X-Git-Tag: 0.51~1^2~9^2~20 X-Git-Url: https://git.m6w6.name/?a=commitdiff_plain;h=357e1856bb92abd6bef6423f1d95e8afb17a872d;p=m6w6%2Flibmemcached Update docs. --- diff --git a/docs/bin/memaslap.rst b/docs/bin/memaslap.rst index b69bb3f8..fa73b51f 100644 --- a/docs/bin/memaslap.rst +++ b/docs/bin/memaslap.rst @@ -18,12 +18,14 @@ DESCRIPTION ----------- -memaslap is a load generation and benchmark tool for :program:`memcached()` -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. Furthermore, it also testss data +:program:`memaslap` is a load generation and benchmark tool for memcached +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. Furthermore, it also testss data verification, expire-time verification, UDP, binary protocol, facebook test, replication test, multi-get and reconnection, etc. -Memslap manages network connections like memcached with +Memaslap manages network connections like memcached with libevent. Each thread of memaslap is bound with a CPU core, all the threads don't communicate with each other, and there are several socket connections in each thread. Each connection keeps key size distribution, @@ -194,9 +196,9 @@ ________________________________________________________________________________ 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 testss multiple servers. The only +the ways in which memaslap tests multiple servers. The only limitation is that the number of servers cannot be greater than the number -of threads. The other way to tests multiple servers is for replication +of threads. The other way to test multiple servers is for replication test. Each concurrency has one socket connection to each memcached server. For the implementation, memaslap can set some objects to one memcached server, and get these objects from the other servers. @@ -208,7 +210,7 @@ pack and send the commands together. Memslap testss both the ASCII protocol and binary protocol, but it runs on the ASCII protocol by default. Memslap by default runs on the TCP protocol, but it also -testss UDP. Because UDP is unreliable, dropped packages and out-of-order +tests UDP. Because UDP is unreliable, dropped packages and out-of-order packages may occur. Memslap creates a memory buffer to handle these problems. Memslap tries to read all the response data of one command from the server and reorders the response data. If some packages @@ -314,7 +316,7 @@ number of them. The default number of threads is 1; the default number of concurrency is 16. The user can use “—threads” and “--concurrency” to specify these variables. -If the system testss setting CPU affinity and the number of threads +If the system tests setting CPU affinity and the number of threads specified by the user is greater than 1, memaslap will try to bind each thread to a different CPU core. So if you want to get the best performance memaslap, it is better to specify the number of diff --git a/docs/hashkit_create.rst b/docs/hashkit_create.rst index 8935b2d0..bf96da75 100644 --- a/docs/hashkit_create.rst +++ b/docs/hashkit_create.rst @@ -48,12 +48,12 @@ RETURN VALUE ------------ -:c:func:`hashkit_create()` and :c:func:`hashkit_clone()` will return NULL on failure or -non-NULL on success. +:c:func:`hashkit_create()` and :c:func:`hashkit_clone()` will return NULL on +failure or non-NULL on success. :c:func:`hashkit_is_allocated()` returns true if the memory for the hashkit -object was allocated inside of :c:func:`hashkit_create()` or :c:func:`hashkit_clone()`, -otherwise it is false and was user-supplied memory. +object was allocated inside of :c:func:`hashkit_create()` or +:c:func:`hashkit_clone()`, otherwise it is false and was user-supplied memory. ---- @@ -63,3 +63,13 @@ HOME To find out more information please check: `http://libmemcached.org/ `_ + + + +-------- +SEE ALSO +-------- + + +:manpage:`hashkit_create(3)` :manpage:`hashkit_value(3)` :manpage:`hashkit_set_hash_fn(3)` + diff --git a/docs/hashkit_functions.rst b/docs/hashkit_functions.rst index 9342a4d4..737171d4 100644 --- a/docs/hashkit_functions.rst +++ b/docs/hashkit_functions.rst @@ -71,6 +71,5 @@ SEE ALSO -------- -hashkit_create(3) hashkit_value(3) hashkit_set_hash_fn(3) -hashkit_set_continuum_hash_fn(3) +:manpage:`hashkit_create(3)` :manpage:`hashkit_value(3)` :manpage:`hashkit_set_hash_fn(3)` :manpage:`hashkit_set_continuum_hash_fn(3)` diff --git a/docs/hashkit_value.rst b/docs/hashkit_value.rst index f768f887..f418a394 100644 --- a/docs/hashkit_value.rst +++ b/docs/hashkit_value.rst @@ -26,7 +26,7 @@ DESCRIPTION ----------- -The hashkit_value() function generates a 32-bit hash value from the +The :c:func:`hashkit_value()` function generates a 32-bit hash value from the given key and key_length. The hash argument is an initialized hashkit object, and distribution type and hash function is used from this object while generating the value. @@ -54,5 +54,5 @@ SEE ALSO -------- -hashkit_create(3) hashkit_set_distribution(3) hashkit_set_hash_fn(3) +:manpage:`hashkit_create(3)` :manpage:`hashkit_set_distribution(3)` :manpage:`hashkit_set_hash_fn(3)` diff --git a/docs/libhashkit.rst b/docs/libhashkit.rst index d13b8757..8866737a 100644 --- a/docs/libhashkit.rst +++ b/docs/libhashkit.rst @@ -15,7 +15,8 @@ Introducing libhashkit DESCRIPTION ----------- -:program:'libhashkit' is a small and thread-safe client library that provides a collection of useful hashing algorithm. libhashkit is distributed with libmemcached. + +libhashkit is a small and thread-safe client library that provides a collection of useful hashing algorithm. libhashkit is distributed with libmemcached. ---- diff --git a/docs/libmemcached.rst b/docs/libmemcached.rst index 78af3e32..80da8fe8 100644 --- a/docs/libmemcached.rst +++ b/docs/libmemcached.rst @@ -33,7 +33,7 @@ DESCRIPTION system, generic in nature, but intended for use in speeding up dynamic web applications by alleviating database load." `http://danga.com/memcached/ `_ -\ **libmemcached**\ is a small, thread-safe client library for the +:program:`libmemcached` is a small, thread-safe client library for the memcached protocol. The code has all been written to allow for both web and embedded usage. It handles the work behind routing individual keys to specific servers specified by the developer (and values are @@ -41,16 +41,17 @@ matched based on server order as supplied by the user). It implements a modular and consistent method of object distribution. There are multiple implemented routing and hashing methods. See the -memcached_behavior_set() manpage for more information. +:c:func:`memcached_behavior_set()` manpage for more information. -All operations are performed against a :c:type:`memcached_st` structure. +All operations are performed against a :c:type:`memcached_st` structure. These structures can either be dynamically allocated or statically -allocated and then initialized by memcached_create(). Functions have been -written in order to encapsulate the :c:type:`memcached_st` . It is not +allocated and then initialized by :c:func:`memcached_create()`. Functions have +been written in order to encapsulate the :c:type:`memcached_st`. It is not recommended that you operate directly against the structure. -Nearly all functions return a :c:type:`memcached_return_t`\ value. -This value can be translated to a printable string with memcached_strerror(3). +Nearly all functions return a :c:type:`memcached_return_t` value. +This value can be translated to a printable string with +:c:type:`memcached_strerror()`. 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. @@ -58,7 +59,7 @@ 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. -:c:type:`memcached_st` structures are thread-safe, but each thread must +:c:type:`memcached_st` structures are thread-safe, but each thread must contain its own structure (that is, if you want to share these among threads you must provide your own locking). No global variables are used in this library. @@ -70,7 +71,7 @@ PKG_CHECK_MODULES(DEPS, libmemcached >= 0.8.0) AC_SUBST(DEPS_CFLAGS) AC_SUBST(DEPS_LIBS) -Some features of the library must be enabled through memcached_behavior_set(). +Some features of the library must be enabled through :c:func:`memcached_behavior_set()`. Hope you enjoy it! @@ -131,10 +132,9 @@ THREADS AND PROCESSES When using threads or forked processes it is important to keep one instance -of :c:type:`memcached_st` per process or thread. Without creating your own locking -structures you can not share a single :c:type:`memcached_st`. However, you can call -memcached_quit(3) on a :c:type:`memcached_st` and then use the resulting cloned -structure. +of :c:type:`memcached_st` per process or thread. Without creating your own +locking structures you can not share a single :c:type:`memcached_st`. However, +you can call :c:func:`memcached_quit()` on a :c:type:`memcached_st` and then use the resulting cloned structure. ---- diff --git a/docs/libmemcached_configuration.rst b/docs/libmemcached_configuration.rst index 4cfec4a8..3c32d5d8 100644 --- a/docs/libmemcached_configuration.rst +++ b/docs/libmemcached_configuration.rst @@ -185,7 +185,7 @@ RETURN ------ -memcached() returns a pointer to the memcached_st that was +:c:func:`memcached()` returns a pointer to the memcached_st that was created (or initialized). On an allocation failure, it returns NULL. diff --git a/docs/libmemcached_examples.rst b/docs/libmemcached_examples.rst index 81137e86..a9e30b30 100644 --- a/docs/libmemcached_examples.rst +++ b/docs/libmemcached_examples.rst @@ -21,15 +21,16 @@ Connecting to servers .. code-block:: c - const char *config_string= "--SERVER=host10.example.com --SERVER=host11.example.com --SERVER=host10.example.com" - memcached_st *memc= memcached(config_string, strlen(config_string); - { - ... - } + const char *config_string= "--SERVER=host10.example.com --SERVER=host11.example.com --SERVER=host10.example.com" + memcached_st *memc= memcached(config_string, strlen(config_string); + { + ... + } memcached_free(memc); -In the above code you create a \ ``memcached_st``\ object with three server by making use of :manpage:`memcached_create_with_options(3)`. +In the above code you create a :c:type:`memcached_st` object with three server +by making use of :c:func:`memcached_create_with_options()`. -------------------------- @@ -40,6 +41,8 @@ Creating a pool of servers .. code-block:: c +Creating a pool of Servers:: + const char *config_string= "--SERVER=host10.example.com --SERVER=host11.example.com --SERVER=host10.example.com"; memcached_pool_st* pool= memcached_pool(config_string, strlen(config_string)); @@ -62,10 +65,10 @@ Creating a pool of servers -In the above code you create a \ ``memcached_pool_st``\ object with three -server by making use of :manpage:`memcached_pool(3)`. +In the above code you create a :c:type:`memcached_pool_st` object with three +server by making use of :c:func:`memcached_pool()`. -When memcached_pool_destroy() all memory will be released that is associated +When :c:func:`memcached_pool_destroy()` all memory will be released that is associated with the pool. @@ -77,6 +80,8 @@ Adding a value to the server .. code-block:: c +Adding a value to the Server:: + char *key= "foo"; char *value= "value"; @@ -104,14 +109,14 @@ Fetching multiple values size_t key_length[]= {5, 3, 4}; unsigned int x; uint32_t flags; - + char return_key[MEMCACHED_MAX_KEY]; size_t return_key_length; char *return_value; size_t return_value_length; - + rc= memcached_mget(memc, keys, key_length, 3); - + x= 0; while ((return_value= memcached_fetch(memc, return_key, &return_key_length, &return_value_length, &flags, &rc))) @@ -122,7 +127,7 @@ Fetching multiple values Notice that you freed values returned from memcached_fetch(). The define -\ ``MEMCACHED_MAX_KEY``\ is provided for usage. +:c:type:`MEMCACHED_MAX_KEY` is provided for usage. diff --git a/docs/libmemcachedutil.rst b/docs/libmemcachedutil.rst index 091d9011..e50c800d 100644 --- a/docs/libmemcachedutil.rst +++ b/docs/libmemcachedutil.rst @@ -23,8 +23,8 @@ DESCRIPTION ----------- -\ **libmemcachedutil**\ is a small and thread-safe client library that provides -extra functionality built on top of \ **libmemcached**\ . +:program:`libmemcachedutil` is a small and thread-safe client library that +provides extra functionality built on top of :program:`libmemcached`. ------- @@ -32,10 +32,10 @@ THREADS ------- -Do not try to access an instance of \ ``memcached_st``\ from multiple threads +Do not try to access an instance of :c:type:`memcached_st` from multiple threads at the same time. If you want to access memcached from multiple threads -you should either clone the \ ``memcached_st``\ , or use the memcached pool -implementation. see memcached_pool_create(3). +you should either clone the :c:type:`memcached_st`, or use the memcached pool +implementation. see :c:func:`memcached_pool_create()`. ---- @@ -52,6 +52,5 @@ SEE ALSO -------- -:manpage:`libmemcached(3)` -:manpage:`memcached_pool_create(3)` :manpage:`memcached_pool_destroy(3)` :manpage:`memcached_pool_pop(3)` :manpage:`memcached_pool_push(3)` +:manpage:`libmemcached(3)` :manpage:`memcached_pool_create(3)` :manpage:`memcached_pool_destroy(3)` :manpage:`memcached_pool_pop(3)` :manpage:`memcached_pool_push(3)` diff --git a/docs/memcached_analyze.rst b/docs/memcached_analyze.rst index 56fbf1f3..9a0c49d2 100644 --- a/docs/memcached_analyze.rst +++ b/docs/memcached_analyze.rst @@ -24,16 +24,16 @@ 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 -\ ``memcached_analysis_st``\ structure. You are responsible for freeing this structure. +:program:`libmemcached` has the ability to query a memcached server (or +collection of servers) for their current state. Queries to find state return a +:c:type:`memcached_analysis_st` structure. You are responsible for freeing this structure. -memcached_analyze() analyzes useful information based on the provided servers -and sets the result to the \ ``memcached_analysis_st``\ structure. The return value -must be freed by the calling application. +:c:func:`memcached_analyze()` analyzes useful information based on the +provided servers and sets the result to the :c:type:`memcached_analysis_st` +structure. The return value must be freed by the calling application. -A command line tool, memstat(1) with the option --analyze, is provided so that -you do not have to write an application to use this method. +A command line tool, :c:func:`memstat()` with the option :option:`--analyze`, +is provided so that you do not have to write an application to use this method. ------ @@ -41,11 +41,11 @@ RETURN ------ -A pointer to the allocated \ ``memcached_analysis_st``\ structure on success and -a NULL pointer on failure. You may inspect the error detail by checking the -\ ``memcached_return_t``\ value. +A pointer to the allocated :c:type:`memcached_analysis_st` structure on +success and a NULL pointer on failure. You may inspect the error detail by +checking the :c:type:`memcached_return_t` value. -Any method returning a \ ``memcached_analysis_st``\ expects you to free the +Any method returning a :c:type:`memcached_analysis_st` expects you to free the memory allocated for it. diff --git a/docs/memcached_append.rst b/docs/memcached_append.rst index 20244c76..a99b2cbc 100644 --- a/docs/memcached_append.rst +++ b/docs/memcached_append.rst @@ -30,43 +30,48 @@ DESCRIPTION ----------- -memcached_prepend() and memcached_append are used to +:c: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(1) which is 1.4 or below, or when using the text protocol. -You must supply both a value and a length. Optionally you +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 +protocol. 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. +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. -memcached_prepend() places a segment of data before the last piece of data -stored. Currently expiration and key are not used in the server. +:c: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. -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. +:c: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. -memcached_prepend_by_key() and memcached_append_by_key_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. +:c:func:`memcached_prepend_by_key()` and +:c:func:`memcached_append_by_key_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. -If you are looking for performance, memcached_set() with non-blocking IO is -the fastest way to store data on the server. +If you are looking for performance, :c:func:`memcached_set()` with non-blocking +IO is the fastest way to store data on the server. -All of the above functions are testsed with the \ ``MEMCACHED_BEHAVIOR_USE_UDP``\ -behavior enabled. However, when using these operations with this behavior on, there -are limits to the size of the payload being sent to the server. The reason for -these limits is that the Memcached Server does not allow multi-datagram requests +All of the above functions are testsed with the +:c:type:`MEMCACHED_BEHAVIOR_USE_UDP` behavior enabled. However, when using +these operations with this behavior on, there are limits to the size of the +payload being sent to the server. The reason for these limits is that the +Memcached Server does not allow multi-datagram requests and the current server implementation sets a datagram size to 1400 bytes. Due to protocol overhead, the actual limit of the user supplied data is less than 1400 bytes and depends on the protocol in use as, well as the operation being -executed. When running with the binary protocol, \ `` MEMCACHED_BEHAVIOR_BINARY_PROTOCOL``\ , -the size of the key,value, flags and expiry combined may not exceed 1368 bytes. -When running with the ASCII protocol, the exact limit fluctuates depending on -which function is being executed and whether the function is a cas operation -or not. For 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. +executed. When running with the binary protocol, +:c:type:`MEMCACHED_BEHAVIOR_BINARY_PROTOCOL`, the size of the key,value, +flags and expiry combined may not exceed 1368 bytes. When running with the +ASCII protocol, the exact limit fluctuates depending on which function is +being executed and whether the function is a cas operation or not. For +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 :c:type:`MEMCACHED_WRITE_FAILURE` will be returned. ------ @@ -74,9 +79,10 @@ RETURN ------ -All methods return a value of type \ ``memcached_return_t``\ . -On success the value will be \ ``MEMCACHED_SUCCESS``\ . -Use memcached_strerror() to translate this value to a printable string. +All methods return a value of type :c:type:`memcached_return_t`. +On success the value will be :c:type:`MEMCACHED_SUCCESS`. +Use :c:func:`memcached_strerror()` to translate this value to a printable +string. ---- @@ -93,5 +99,5 @@ SEE ALSO -------- -memcached(1) libmemached(3) memcached_strerror(3) memcached_set(3) memcached_add(3) memcached_cas(3) memcached_replace(3) +:manpage:`memcached(1)` :manpage:`libmemached(3)` :manpage:`memcached_strerror(3)` :manpage:`memcached_set(3)` :manpage:`memcached_add(3)` :manpage:`memcached_cas(3)` :manpage:`memcached_replace(3)`