From: Brian Aker Date: Tue, 19 Apr 2011 22:43:26 +0000 (-0700) Subject: Merge in additional documentation. X-Git-Tag: 0.51~12^2~1 X-Git-Url: https://git.m6w6.name/?a=commitdiff_plain;h=0f16555031c7f44d1acd034ff74e628c51a72dac;p=m6w6%2Flibmemcached Merge in additional documentation. --- diff --git a/docs/hashkit_create.rst b/docs/hashkit_create.rst index cf11e83e..e0c9c71c 100644 --- a/docs/hashkit_create.rst +++ b/docs/hashkit_create.rst @@ -3,35 +3,24 @@ Creating a hashkit structure ============================ -Create and destroy hashkit objects - - -------- -LIBRARY -------- - - -C Library for hashing algorithms (libmemcached, -lhashkit) - - -------- SYNOPSIS -------- +C Library for hashing algorithms (libmemcached, -lhashkit) -.. code-block:: perl - - #include - - hashkit_st *hashkit_create(hashkit_st *hash); +#include - hashkit_st *hashkit_clone(hashkit_st *destination, const hashkit_st *ptr); +.. c:function:: hashkit_st *hashkit_create(hashkit_st *hash); - void hashkit_free(hashkit_st *hash); - - bool hashkit_is_allocated(const hashkit_st *hash); +.. c:function:: hashkit_st *hashkit_clone(hashkit_st *destination, const hashkit_st *ptr); + +.. c:function:: void hashkit_free(hashkit_st *hash); + +.. c:function:: bool hashkit_is_allocated(const hashkit_st *hash); +Compile and link with -lmemcached ----------- diff --git a/docs/libmemcached.rst b/docs/libmemcached.rst index bb0f0461..23ec93b4 100644 --- a/docs/libmemcached.rst +++ b/docs/libmemcached.rst @@ -10,6 +10,17 @@ SYNOPSIS Compile and link with -lmemcached +libMemcached is an open source C/C++ client library and tools for the memcached server (http://danga.com/memcached). It has been designed to be light on memory usage, thread safe, and provide full access to server side methods. + +libMemcached was designed to provide the greatest number of options to use Memcached. Some of the features provided: + +1. Asynchronous and Synchronous Transport Support. +2. Consistent Hashing and Distribution. +3. Tunable Hashing algorithm to match keys. +4. Access to large object support. +5. Local replication. +6. A complete reference guide and documentation to the API. +7. Tools to Manage your Memcached networks. ----------- DESCRIPTION @@ -21,14 +32,14 @@ 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 -memcached protocol. The code has all been written with an eye to allow +memcached protocol. The code has all been written to allow for both web and embedded usage. It handles the work behind routing -particular keys to specific servers that you specify (and values are -matched based on server order as supplied by you). It implements both -a modula and consistent method of object distribution. +individual keys to specific servers specified by the developer (and values are +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. +memcached_behavior_set() manpage for more information. All operations are performed against a \ ``memcached_st``\ structure. These structures can either be dynamically allocated or statically @@ -117,9 +128,9 @@ THREADS AND PROCESSES --------------------- -When using threads or forked processes it is important to keep an instance +When using threads or forked processes it is important to keep one instance of \ ``memcached_st``\ per process or thread. Without creating your own locking -structures you can not share a single \ ``memcached_st``\ . You can though call +structures you can not share a single \ ``memcached_st``\ . However, you can call memcached_quit(3) on a \ ``memcached_st``\ and then use the resulting cloned structure. diff --git a/docs/memcached_callback.rst b/docs/memcached_callback.rst index 787bc49a..aac70391 100644 --- a/docs/memcached_callback.rst +++ b/docs/memcached_callback.rst @@ -41,73 +41,71 @@ function set by memcached_callback_set(). memcached_callback_set() changes the function/structure assigned by a callback flag. No connections are reset. -You can use MEMCACHED_CALLBACK_USER_DATA to provide custom context if required for any -of the callbacks +You can use MEMCACHED_CALLBACK_USER_DATA to provide custom context if required for any of the callbacks. .. c:var:: MEMCACHED_CALLBACK_CLEANUP_FUNCTION - When memcached_delete() is called this function will be excuted. At the - point of its execution all connections have been closed. +When memcached_delete() is called this function will be excuted. At the point of its execution all connections are closed. .. c:var:: MEMCACHED_CALLBACK_CLONE_FUNCTION - When memcached_delete() is called this function will be excuted. At the - point of its execution all connections have been closed. +When memcached_delete() is called this function will be excuted. At the +point of its execution all connections are closed. .. c:var:: MEMCACHED_CALLBACK_PREFIX_KEY - You can set a value which will be used to create a domain for your keys. - The value specified here will be prefixed to each of your keys. The value can not - be greater then MEMCACHED_PREFIX_KEY_MAX_SIZE - 1 and will reduce MEMCACHED_MAX_KEY by - the value of your key. The prefix key is only applied to the primary key, - not the master key. MEMCACHED_FAILURE will be returned if no key is set. In the case - of a key which is too long MEMCACHED_BAD_KEY_PROVIDED will be returned. +You can set a value which will be used to create a domain for your keys. +The value specified here will be prefixed to each of your keys. The value can not be greater then MEMCACHED_PREFIX_KEY_MAX_SIZE - 1 and will reduce MEMCACHED_MAX_KEY by the value of your key. + +The prefix key is only applied to the primary key, not the master key. MEMCACHED_FAILURE will be returned if no key is set. In the case of a key which is too long, MEMCACHED_BAD_KEY_PROVIDED will be returned. - If you set a value with the value being NULL then the prefix key is disabled. +If you set a value with the value being NULL then the prefix key is disabled. .. c:var:: MEMCACHED_CALLBACK_USER_DATA - This allows you to store a pointer to a specifc piece of data. This can be - retrieved from inside of memcached_fetch_execute(). Cloning a memcached_st - will copy the pointer to the clone. +This allows you to store a pointer to a specifc piece of data. This can be +retrieved from inside of memcached_fetch_execute(). Cloning a memcached_st +will copy the pointer to the clone. .. c:var:: MEMCACHED_CALLBACK_MALLOC_FUNCTION - DEPRECATED: use memcached_set_memory_allocators instead. +DEPRECATED: use memcached_set_memory_allocators instead. .. c:var:: MEMCACHED_CALLBACK_REALLOC_FUNCTION - DEPRECATED: use memcached_set_memory_allocators instead. +DEPRECATED: use memcached_set_memory_allocators instead. .. c:var:: MEMCACHED_CALLBACK_FREE_FUNCTION - DEPRECATED: use memcached_set_memory_allocators instead. +DEPRECATED: use memcached_set_memory_allocators instead. .. c:var:: MEMCACHED_CALLBACK_GET_FAILURE - This function implements the read through cache behavior. On failure of retrieval this callback will be called. - You are responsible for populating the result object provided. This result object will then be stored in the server and - returned to the calling process. You must clone the memcached_st in order to - make use of it. The value will be stored only if you return - MEMCACHED_SUCCESS or MEMCACHED_BUFFERED. Returning MEMCACHED_BUFFERED will - cause the object to be buffered and not sent immediatly (if this is the default behavior based on your connection setup this will happen automatically). +This function implements the read through cache behavior. On failure of retrieval this callback will be called. + +You are responsible for populating the result object provided. This result object will then be stored in the server and returned to the calling process. + +You must clone the memcached_st in order to +make use of it. The value will be stored only if you return +MEMCACHED_SUCCESS or MEMCACHED_BUFFERED. Returning MEMCACHED_BUFFERED will +cause the object to be buffered and not sent immediatly (if this is the default behavior based on your connection setup this will happen automatically). - The prototype for this is: - memcached_return_t (\*memcached_trigger_key)(memcached_st \*ptr, char \*key, size_t key_length, memcached_result_st \*result); +The prototype for this is: +memcached_return_t (\*memcached_trigger_key)(memcached_st \*ptr, char \*key, size_t key_length, memcached_result_st \*result); diff --git a/docs/memcached_delete.rst b/docs/memcached_delete.rst index 5afccee7..f628f69e 100644 --- a/docs/memcached_delete.rst +++ b/docs/memcached_delete.rst @@ -25,8 +25,8 @@ memcached_delete_by_key() works the same, but it takes a master key to find the given value. Expiration works by placing the item into a delete queue, which means that -it won't possible to retrieve it by the "get" command, but "add" and -"replace" command with this key will also fail (the "set" command will +it won't be possible to retrieve it by the "get" command. The "add" and +"replace" commands with this key will also fail (the "set" command will succeed, however). After the time passes, the item is finally deleted from server memory. Please note the the Danga memcached server removed tests for expiration in diff --git a/docs/memcached_dump.rst b/docs/memcached_dump.rst index 9b6e887e..a7dcb4fe 100644 --- a/docs/memcached_dump.rst +++ b/docs/memcached_dump.rst @@ -42,12 +42,12 @@ DESCRIPTION ----------- -memcached_dump() is used to get a list of keys found memcached(1) servers. +memcached_dump() is used to get a list of keys found in memcached(1) servers. Because memcached(1) does not guarentee 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 binar protocol is not testsed. +Currently the binary protocol is not testsed. ------ diff --git a/docs/memcached_get.rst b/docs/memcached_get.rst index f6813d45..dcb931c7 100644 --- a/docs/memcached_get.rst +++ b/docs/memcached_get.rst @@ -65,7 +65,7 @@ memcached_return_t pointer to hold any error. The object will be returned upon success and NULL will be returned on failure. MEMCACHD_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 -memcached_fetch() musted be free'ed by the caller. memcached_fetch() will +memcached_fetch() must be freed by the caller. memcached_fetch() will be DEPRECATED in the near future, memcached_fetch_result() should be used instead. @@ -89,7 +89,7 @@ memcached_mget_execute() and memcached_mget_execute_by_key() is similar to memcached_mget(), but it may trigger the supplied callbacks with result sets while sending out the queries. If you try to perform a really large multiget with memcached_mget() you may encounter a -deadlock in the OS kernel (we fail to write data to the socket because +deadlock in the OS kernel (it will fail to write data to the socket because the input buffer is full). memcached_mget_execute() solves this problem by processing some of the results before continuing sending out requests. Please note that this function is only available in the @@ -100,9 +100,9 @@ as memcached_get() and 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 testsed when the \ ``MEMCACHED_BEHAVIOR_USE_UDP``\ +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 +\ ``MEMCACHED_NOT_SUPPORTED``\ being returned, or for those functions which do not return a \ ``memcached_return_t``\ , the error function parameter will be set to \ ``MEMCACHED_NOT_SUPPORTED``\ . diff --git a/docs/memcached_memory_allocators.rst b/docs/memcached_memory_allocators.rst index 7f1cd10e..40219079 100644 --- a/docs/memcached_memory_allocators.rst +++ b/docs/memcached_memory_allocators.rst @@ -45,7 +45,7 @@ DESCRIPTION ----------- -libmemcached(3) allows you to specify your own memory allocators optimized +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. memcached_set_memory_allocators() is used to set the memory allocators used diff --git a/docs/memcached_result_st.rst b/docs/memcached_result_st.rst index 9243d6b4..e8aba518 100644 --- a/docs/memcached_result_st.rst +++ b/docs/memcached_result_st.rst @@ -59,9 +59,9 @@ DESCRIPTION libmemcached(3) can optionally return a 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 +pointer returns, in that they are forward compatible with new return items that future memcached servers may implement (the best current example of -this is the CAS return item). The structures can also be reused which will +this is the CAS return item). The structures can also be reused, which will save on calls to malloc(3). It is suggested that you use result objects over char \* return functions. @@ -72,7 +72,7 @@ memcached_result_create() will either allocate memory for a memcached_result_st or will initialize a structure passed to it. memcached_result_free() will deallocate any memory attached to the -structure. If the structure was also alloacted, it will deallocate it. +structure. If the structure was also allocated, it will deallocate it. memcached_result_key_value() returns the key value associated with the current result object. @@ -91,7 +91,7 @@ current result object. memcached_result_cas() returns the cas associated with the current result object. This value will only be available if the server -testss it. +tests it. memcached_result_set_value() takes a byte array and a size and sets the result to this value. This function is used for trigger responses. diff --git a/docs/memcached_sasl.rst b/docs/memcached_sasl.rst index 30aa72ca..bf0251dd 100644 --- a/docs/memcached_sasl.rst +++ b/docs/memcached_sasl.rst @@ -44,7 +44,7 @@ libsasl to perform SASL authentication. Please note that SASL requires the memcached binary protocol, and you have to specify the callbacks before you connect to the server. -memcached_set_sasl_auth_data() is a helper function for you defining +memcached_set_sasl_auth_data() is a helper function defining the basic functionality for you, but it will store the username and password in memory. If you choose to use this method you have to call memcached_destroy_sasl_auth_data before calling memcached_free to avoid diff --git a/docs/memcached_set.rst b/docs/memcached_set.rst index c2f08b3c..4cdbd994 100644 --- a/docs/memcached_set.rst +++ b/docs/memcached_set.rst @@ -49,8 +49,8 @@ DESCRIPTION memcached_set(), memcached_add(), and memcached_replace() are all used to store information on the server. All methods take a key, and its length to store the object. Keys are currently limited to 250 characters by the -memcached(1) server. You must also supply a value and a length. Optionally you -may tests an expiration time for the object and a 16 byte value (it is +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). memcached_set() will write an object to the server. If an object already @@ -87,12 +87,12 @@ If you are looking for performance, 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. But when using these operations with this behavior on, there +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 Memcahed Server does not allow multi-datagram requests +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 +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 diff --git a/docs/memcached_version.rst b/docs/memcached_version.rst index 01403a16..a670c78f 100644 --- a/docs/memcached_version.rst +++ b/docs/memcached_version.rst @@ -39,7 +39,7 @@ DESCRIPTION memcached_lib_version() is used to return a simple version string representing -the libmemcached version (version of the client library, not server) +the libmemcached version (client library version, not server version) 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 diff --git a/docs/memcapable.rst b/docs/memcapable.rst index a8ac4e43..b9d2f5a8 100644 --- a/docs/memcapable.rst +++ b/docs/memcapable.rst @@ -16,29 +16,29 @@ SYNOPSIS .. option:: -h hostname - Specify the hostname to connect to. The default is \ *localhost*\ +Specify the hostname to connect to. The default is \ *localhost*\ .. option:: -p port - Specify the port number to connect to. The default is \ *11211*\ +Specify the port number to connect to. The default is \ *11211*\ .. option:: -c - Generate a coredump when it detects an error from the server. +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. +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. +Set the timeout from an IO operation to/from the server to \ *n*\ seconds. ----------- DESCRIPTION diff --git a/docs/memcp.rst b/docs/memcp.rst index 6e12bedd..7e620cca 100644 --- a/docs/memcp.rst +++ b/docs/memcp.rst @@ -26,11 +26,10 @@ DESCRIPTION It is similar to the standard UNIX cp(1) command. The key names will be the names of the files, -without any directory path part. +without any directory path. You can specify servers via the \ **--servers**\ option or via the -environment variable \ ``MEMCACHED_SERVERS``\ . If you specify neither of -these, the final value in the command line list is the name of a +environment variable \ ``MEMCACHED_SERVERS``\. If you do not specify either these, the final value in the command line list is the name of a server(s). For a full list of operations run the tool with the \ **--help**\ option. diff --git a/docs/memdump.rst b/docs/memdump.rst index 74e1254f..fbdb8c1c 100644 --- a/docs/memdump.rst +++ b/docs/memdump.rst @@ -21,7 +21,7 @@ DESCRIPTION ----------- -\ **memdump**\ currently dumps a list of "keys" from all servers that +\ **memdump**\ dumps a list of "keys" from all servers that it is told to fetch from. Because memcached does not guarentee to provide all keys it is not possible to get a complete "dump". diff --git a/docs/memerror.rst b/docs/memerror.rst index 7e2d967f..7501c071 100644 --- a/docs/memerror.rst +++ b/docs/memerror.rst @@ -3,7 +3,7 @@ memerror - translate an error code to a string ============================================== -Translate a memcached error code to a string +Translates a memcached error code into a string -------- @@ -21,7 +21,7 @@ DESCRIPTION ----------- -\ **memerror**\ translate an error code from libmemcached(3) to a human +\ **memerror**\ translate an error code from libmemcached(3) into a human readable string. For a full list of operations run the tool with the \ **--help**\ option. diff --git a/docs/memflush.rst b/docs/memflush.rst index 6cb04728..e02969bd 100644 --- a/docs/memflush.rst +++ b/docs/memflush.rst @@ -22,7 +22,7 @@ DESCRIPTION \ **memflush**\ resets the contents of memcached(1) servers. -This means all data in these servers will be deleted. +This means that all data in the specified servers will be deleted. You can specify servers via the \ **--servers**\ option or via the environment variable \ ``MEMCACHED_SERVERS``\ . diff --git a/docs/memslap.rst b/docs/memslap.rst index cde4ace7..1996b99f 100644 --- a/docs/memslap.rst +++ b/docs/memslap.rst @@ -20,12 +20,9 @@ DESCRIPTION \ **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. +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. -You can specify servers via the \ **--servers**\ option or via the -environment variable \ ``MEMCACHED_SERVERS``\ . +You can specify servers via the \ **--servers**\ option or via the environment variable \ ``MEMCACHED_SERVERS``\ . --------