From: Michael Wallner Date: Fri, 28 Feb 2020 19:19:44 +0000 (+0100) Subject: docs: sanitize X-Git-Tag: 1.1.0-beta1~250^2~5 X-Git-Url: https://git.m6w6.name/?a=commitdiff_plain;h=0a654f848e13d470fb07b044347f2e91d6941807;p=awesomized%2Flibmemcached docs: sanitize --- diff --git a/CMakeConfig.txt b/CMakeConfig.txt index 0c8a118b..41b76324 100644 --- a/CMakeConfig.txt +++ b/CMakeConfig.txt @@ -8,7 +8,7 @@ option(BUILD_TESTING "whether to enable build of the test suite" option(BUILD_DOCSONLY "build *only* documentation" OFF) option(BUILD_DOCS "build documentation" - OFF) + ${BUILD_DOCSONLY}) option(BUILD_DOCS_HTML "build HTML docs" ${BUILD_DOCS}) option(BUILD_DOCS_MAN "build manpages" @@ -40,9 +40,9 @@ endif() if(BUILD_DOCS) set(SPHINX_OPTIONS "" CACHE STRING "additional sphinx-build command line options") - set(SPHINX_THEME "nature" #"sphinx_rtd_theme" + set(SPHINX_THEME "sphinx_rtd_theme" CACHE STRING "sphinx HTML theme") - set(SPHINX_THEME_OPTIONS "" #"'collapse_navigation':False, 'navigation_depth':2, 'titles_only':False, 'includehidden':False" + set(SPHINX_THEME_OPTIONS "" CACHE STRING "sphinx HTML theme options") set(SPHINX_EXTENSIONS "" CACHE STRING "comma separated list of quoted sphinx extensions") diff --git a/docs/gh-pages/publish.sh b/docs/gh-pages/publish.sh index 6095d45f..5b43fa24 100755 --- a/docs/gh-pages/publish.sh +++ b/docs/gh-pages/publish.sh @@ -14,7 +14,7 @@ fi mkdir -p build cd build -cmake -DBUILD_DOCSONLY=true ../../.. +cmake -DBUILD_DOCSONLY=true -DBUILD_DOCS_HTML=true ../../.. make html rsync -va --delete --exclude=.git/ docs/html/ ../pages/ diff --git a/docs/source/index.rst b/docs/source/index.rst index ab3e4e75..67c22628 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -5,12 +5,10 @@ libmemcached Manual memcached server (http://memcached.org/). It has been designed to be light on memory usage, thread safe, and provide full access to server side methods. -* :ref:`genindex` -* :ref:`search` .. toctree:: - :titlesonly: :caption: libmemcached + :titlesonly: Introduction libmemcached/index @@ -41,3 +39,8 @@ memory usage, thread safe, and provide full access to server side methods. :hidden: copyright + +Index +----- + +:ref:`genindex` diff --git a/docs/source/libhashkit/hashkit_create.rst b/docs/source/libhashkit/hashkit_create.rst index 630ee0a4..e74550f5 100644 --- a/docs/source/libhashkit/hashkit_create.rst +++ b/docs/source/libhashkit/hashkit_create.rst @@ -1,8 +1,6 @@ Creating a hashkit structure ============================ -Create, copy and free a hashkit structure - SYNOPSIS -------- @@ -22,30 +20,29 @@ SYNOPSIS DESCRIPTION ----------- -The :func:`hashkit_create` function initializes a hashkit object for use. If -you pass a NULL argument for hash, then the memory for the object is -allocated. If you specify a pre-allocated piece of memory, that is -initialized for use. +The `hashkit_create` function initializes a hashkit object for use. If you pass +a NULL argument for hash, then the memory for the object is allocated. If you +specify a pre-allocated piece of memory, that is initialized for use. -The :func:`hashkit_clone` function initializes a hashkit object much like -:func:`hashkit_create`, but instead of using default settings it will use -the settings of the ptr hashkit object. +The `hashkit_clone` function initializes a hashkit object much like +`hashkit_create`, but instead of using default settings it will use 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 `hashkit_free` frees any resources being consumed by the hashkit objects +that were initialized with `hashkit_create` or `hashkit_clone`. -The :func:`hashkit_is_allocated` reports where the memory was allocated -for a hashkit object. +The `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 -failure or non-NULL on success. +`hashkit_create` and `hashkit_clone` will return NULL on failure or non-NULL on +success. -:func:`hashkit_is_allocated` returns true if the memory for the hashkit -object was allocated inside of :func:`hashkit_create` or -:func:`hashkit_clone`, otherwise it is false and was user-supplied memory. +`hashkit_is_allocated` returns true if the memory for the hashkit object was +allocated inside of `hashkit_create` or `hashkit_clone`, otherwise it is false +and was user-supplied memory. SEE ALSO -------- diff --git a/docs/source/libhashkit/hashkit_function.rst b/docs/source/libhashkit/hashkit_function.rst index f238d5db..79b1efea 100644 --- a/docs/source/libhashkit/hashkit_function.rst +++ b/docs/source/libhashkit/hashkit_function.rst @@ -1,11 +1,6 @@ Set Hash Function ================= -.. index:: object: hashkit_st -.. index:: object: hashkit_hash_fn - -Set hash functions to use for calculating values for keys - SYNOPSIS -------- @@ -34,11 +29,11 @@ These functions are used to set and retrieve the key and distribution hash funct RETURN VALUE ------------ -:func:`hashkit_set_function`, :func:`hashkit_set_custom_function` and the distribution equivalents -return :type:`hashkit_return_t` `HASHKIT_SUCCESS` on success. +`hashkit_set_function`, `hashkit_set_custom_function` and the distribution +equivalents return `hashkit_return_t` `HASHKIT_SUCCESS` on success. -:func:`hashkit_get_function` and :func:`hashkit_get_distribution_function` return :type:`hashkit_hash_algorithm_t` -indicating the hash function used. +`hashkit_get_function` and `hashkit_get_distribution_function` return +`hashkit_hash_algorithm_t` indicating the hash function used. SEE ALSO -------- diff --git a/docs/source/libhashkit/hashkit_functions.rst b/docs/source/libhashkit/hashkit_functions.rst index d55ca5c2..04f6ba2b 100644 --- a/docs/source/libhashkit/hashkit_functions.rst +++ b/docs/source/libhashkit/hashkit_functions.rst @@ -1,10 +1,6 @@ Available Hashes ================ -.. index:: object: hashkit_st - -Various hash functions to use for calculating hash values for keys - SYNOPSIS -------- diff --git a/docs/source/libhashkit/hashkit_value.rst b/docs/source/libhashkit/hashkit_value.rst index ab6ef7ac..1522b440 100644 --- a/docs/source/libhashkit/hashkit_value.rst +++ b/docs/source/libhashkit/hashkit_value.rst @@ -1,10 +1,6 @@ Generate hash value =================== -.. index:: object: hashkit_st - -Generate a value for the given key - SYNOPSIS -------- @@ -16,10 +12,10 @@ SYNOPSIS DESCRIPTION ----------- -The :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. +The `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. RETURN VALUE ------------ diff --git a/docs/source/libmemcached.rst b/docs/source/libmemcached.rst index 4f85d96c..5ad21dfc 100644 --- a/docs/source/libmemcached.rst +++ b/docs/source/libmemcached.rst @@ -27,30 +27,28 @@ Memcached. Some of the features provided: DESCRIPTION ----------- -"Memcached is a high-performance, distributed memory object caching -system, generic in nature, but intended for use in speeding up dynamic web -applications by alleviating database load." -`http://memcached.org/ `_ - -`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 -matched based on server order as supplied by the user). It implements -a modular and consistent method of object distribution. +"Memcached is a high-performance, distributed memory object caching system, +generic in nature, but intended for use in speeding up dynamic web applications +by alleviating database load." `http://memcached.org/ `_ + +`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 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 -:func:`memcached_behavior_set` manpage for more information. +`memcached_behavior_set` manpage for more information. -All operations are performed against a :type:`memcached_st` structure. -These structures can either be dynamically allocated or statically -allocated and then initialized by :func:`memcached_create`. Functions have -been written in order to encapsulate the :type:`memcached_st`. It is not -recommended that you operate directly against the structure. +All operations are performed against a `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 `memcached_st`. It is not recommended that you operate directly +against the structure. -Nearly all functions return a :type:`memcached_return_t` value. -This value can be translated to a printable string with -:type:`memcached_strerror`. +Nearly all functions return a `memcached_return_t` value. This value can be +translated to a printable string with `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 @@ -63,30 +61,16 @@ applications can use the same memcached servers. Some features of the library must be enabled through `memcached_behavior_set`. -CONSTANTS ---------- - -A number of constants have been provided for in the library. - -.. only:: man - - See :manpage:`libmemcached_constants(3)`. - -.. only:: html - - See :doc:`libmemcached/constants`. - THREADS AND PROCESSES --------------------- No global variables are used in this library. -:type:`memcached_st` structures are thread-safe, but when using threads or -forked processes it is important to keep one instance of :type:`memcached_st` -per process or thread. Without creating your own locking structures you can not -share a single :type:`memcached_st`. However, you can call -:func:`memcached_quit` on a :type:`memcached_st` and then use the resulting -cloned structure. +`memcached_st` structures are thread-safe, but 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`. However, you can call `memcached_quit` on a `memcached_st` and +then use the resulting cloned structure. SYSTEMTAP --------- diff --git a/docs/source/libmemcached/configuration.rst b/docs/source/libmemcached/configuration.rst index 36b1bc49..8e9c4763 100644 --- a/docs/source/libmemcached/configuration.rst +++ b/docs/source/libmemcached/configuration.rst @@ -4,7 +4,7 @@ libmemcached Configuration SYNOPSIS -------- -#include +#include Compile and link with -lmemcached .. function:: memcached_st *memcached(const char *string, size_t string_length) @@ -25,18 +25,18 @@ General Options: Provide a servername to be used by the client. - Providing a weight will cause weighting to occur with all hosts with each + Providing a weight will cause weighting to occur with all hosts with each server getting a default weight of 1. .. describe:: --SOCKET=\"/?\" - Provide a filepath to a UNIX socket file. Providing a weight will cause - weighting to occur with all hosts with each server getting a default weight + Provide a filepath to a UNIX socket file. Providing a weight will cause + weighting to occur with all hosts with each server getting a default weight of 1. .. describe:: --VERIFY-KEY - Verify that keys that are being used fit within the design of the protocol + Verify that keys that are being used fit within the design of the protocol being used. .. describe:: --REMOVE_FAILED_SERVERS @@ -169,7 +169,7 @@ Other Options: .. describe:: INCLUDE Include a file in configuration. - Unlike --CONFIGURE-FILE= this will not reset `memcached_st`. + Unlike ``--CONFIGURE-FILE=`` this will not reset `memcached_st`. .. describe:: RESET @@ -191,8 +191,8 @@ ENVIRONMENT RETURN VALUE ------------ -:func:`memcached()` returns a pointer to the memcached_st that was -created (or initialized). On an allocation failure, it returns NULL. +`memcached` returns a pointer to the memcached_st that was created (or +initialized). On an allocation failure, it returns NULL. EXAMPLE ------- diff --git a/docs/source/libmemcached/constants.rst b/docs/source/libmemcached/constants.rst index c0d53dff..0952a418 100644 --- a/docs/source/libmemcached/constants.rst +++ b/docs/source/libmemcached/constants.rst @@ -4,12 +4,12 @@ libmemcached Constants and Defaults SYNOPSIS -------- -#include +#include Compile and link with -lmemcached .. c:macro:: LIBMEMCACHED_VERSION_STRING - String value of libmemcached version such as "1.23.4" + String value of libmemcached version such as "|release|" .. c:macro:: LIBMEMCACHED_VERSION_HEX @@ -61,6 +61,10 @@ SYNOPSIS How many extra slots we should build for in the continuum, defaults to 10. +.. c:macro:: MEMCACHED_EXPIRATION_NOT_ADD + + Value ``0xffffffffU`` + .. c:macro:: MEMCACHED_STRIDE This is the "stride" used in the consistent hash used between replicas. diff --git a/docs/source/libmemcached/examples.rst b/docs/source/libmemcached/examples.rst index 69aaf24b..dfd7fa25 100644 --- a/docs/source/libmemcached/examples.rst +++ b/docs/source/libmemcached/examples.rst @@ -6,9 +6,8 @@ Examples for libmemcached DESCRIPTION ----------- -For full examples, test cases are found in tests/\*.c in the main -distribution. These are always up to date, and are used for each test run of -the library. +For full examples, test cases are found in tests/\*.c in the main distribution. +These are always up to date, and are used for each test run of the library. Connecting to servers --------------------- @@ -25,15 +24,18 @@ Connecting to servers } memcached_free(memc); -In the above code you create a :type:`memcached_st` object with three server -by making use of :func:`memcached_create`. +In the above code you create a `memcached_st` object with three server by making +use of `memcached_create`. Creating a pool of servers -------------------------- .. code-block:: c - const char *config_string= "--SERVER=host10.example.com --SERVER=host11.example.com --SERVER=host10.example.com"; + 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)); @@ -53,10 +55,10 @@ Creating a pool of servers */ memcached_pool_destroy(pool); -In the above code you create a :type:`memcached_pool_st` object with three -server by making use of :func:`memcached_pool()`. +In the above code you create a `memcached_pool_st` object with three server by +making use of `memcached_pool()`. -When :func:`memcached_pool_destroy()` all memory will be released that is associated +When `memcached_pool_destroy()` all memory will be released that is associated with the pool. Adding a value to the server diff --git a/docs/source/libmemcached/index.rst b/docs/source/libmemcached/index.rst index ebcf1c7b..478284ad 100644 --- a/docs/source/libmemcached/index.rst +++ b/docs/source/libmemcached/index.rst @@ -32,7 +32,7 @@ libmemcached API index_deprecated .. toctree: - :titlesonlx: + :titlesonly: :caption: Misc index_misc diff --git a/docs/source/libmemcached/memcached_analyze.rst b/docs/source/libmemcached/memcached_analyze.rst index 9cfda0d5..7843e4e8 100644 --- a/docs/source/libmemcached/memcached_analyze.rst +++ b/docs/source/libmemcached/memcached_analyze.rst @@ -1,45 +1,40 @@ Analyzing servers ================= -Analyze server information - SYNOPSIS -------- -.. index:: object: memcached_analysis_st - #include Compile and link with -lmemcached -.. type:: memcached_analysis_st +.. type:: struct memcached_analysis_st memcached_analysis_st - typedef struct memcached_analysis_st memcached_analysis_st; - -.. function:: memcached_analysis_st *memcached_analyze(memcached_st *ptr, memcached_stat_st *stat, memcached_return_t *error) +.. function:: memcached_analysis_st *memcached_analyze(memcached_st *ptr, memcached_stat_st *stat, memcached_return_t *error) DESCRIPTION ----------- -`libmemcached` has the ability to query a memcached server (or -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. +`libmemcached` 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. -: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. +`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. -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. +.. seealso:: :option:`memstat --analyze` + A command line tool to analyze a memcached server. -RETURN ------- +RETURN VALUE +------------ -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. +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. -Any method returning a :type:`memcached_analysis_st` expects you to free the -memory allocated for it. +Any method returning a `memcached_analysis_st` expects you to free the memory +allocated for it. SEE ALSO -------- diff --git a/docs/source/libmemcached/memcached_append.rst b/docs/source/libmemcached/memcached_append.rst index 5aa1ce3f..1a60501f 100644 --- a/docs/source/libmemcached/memcached_append.rst +++ b/docs/source/libmemcached/memcached_append.rst @@ -1,14 +1,11 @@ -Appending or Prepending to data on the server -============================================= - -.. index:: object: memcached_st - -Appending or Prepending to data on the server +Appending or Prepending Data +============================ SYNOPSIS -------- -#include +#include + Compile and link with -lmemcached .. 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) @@ -18,66 +15,74 @@ SYNOPSIS .. function:: memcached_return_t memcached_append_by_key(memcached_st *ptr, const char *group_key, size_t group_key_length, const char *key, size_t key_length, const char *value, size_t value_length, time_t expiration, uint32_t flags) -Compile and link with -lmemcached - DESCRIPTION ----------- -: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 -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. - -: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 -piece of data stored. Currently expiration and key are not used in the server. - -: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 +`memcached_prepend` and memcached_append are used to modify information on a +server. All methods take a ``key``, and ``key_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 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. + +`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. + +`memcached_prepend_by_key` and `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. -If you are looking for performance, :func:`memcached_set` with non-blocking -IO is the fastest way to store data on the server. - -All of the above functions are tested 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 -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. - -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. +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 tested 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 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. + +RETURN VALUE +------------ + +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. 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)` + +.. only:: html + + * :manpage:`memcached(1)` + * :doc:`../libmemcached` + * :doc:`memcached_set` + * :doc:`memcached_cas` + * :doc:`memcached_strerror` diff --git a/docs/source/libmemcached/memcached_auto.rst b/docs/source/libmemcached/memcached_auto.rst index 1171393d..6d1acc88 100644 --- a/docs/source/libmemcached/memcached_auto.rst +++ b/docs/source/libmemcached/memcached_auto.rst @@ -1,12 +1,11 @@ Incrementing and Decrementing Values ==================================== -.. index:: object: memcached_st - SYNOPSIS -------- #include + Compile and link with -lmemcached .. function:: memcached_return_t memcached_increment (memcached_st *ptr, const char *key, size_t key_length, uint32_t offset, uint64_t *value) @@ -24,7 +23,6 @@ SYNOPSIS .. function:: memcached_return_t memcached_decrement_with_initial_by_key (memcached_st *ptr, const char *group_key, size_t group_key_length, const char *key, size_t key_length, uint64_t offset, uint64_t initial, time_t expiration, uint64_t *value) -Compile and link with -lmemcached DESCRIPTION ----------- @@ -33,48 +31,57 @@ DESCRIPTION (overflow and underflow are not detected). This gives you the ability to use memcached to generate shared sequences of values. -memcached_increment takes a key and key length and increments the value by -the offset passed to it. The value is then returned via the uint32_t -value pointer you pass to it. - -memcached_decrement takes a key and keylength and decrements the value by -the offset passed to it. The value is then returned via the uint32_t -value pointer you pass to it. - -memcached_increment_with_initial takes a key and keylength and increments -the value by the offset passed to it. If the object specified by key does -not exist, one of two things may happen: If the expiration value is -MEMCACHED_EXPIRATION_NOT_ADD, the operation will fail. For all other -expiration values, the operation will succeed by seeding the value for that -key with a initial value to expire with the provided expiration time. The -flags will be set to zero.The value is then returned via the uint32_t -value pointer you pass to it. memcached_increment_with_initial is only available -when using the binary protocol. - -memcached_decrement_with_initial takes a key and keylength and decrements -the value by the offset passed to it. If the object specified by key does -not exist, one of two things may happen: If the expiration value is -MEMCACHED_EXPIRATION_NOT_ADD, the operation will fail. For all other -expiration values, the operation will succeed by seeding the value for that -key with a initial value to expire with the provided expiration time. The -flags will be set to zero.The value is then returned via the uint32_t -value pointer you pass to it. memcached_decrement_with_initial is only available -when using the binary protocol. - -:func:`memcached_increment_by_key`, :func:`memcached_decrement_by_key`, -:func:`memcached_increment_with_initial_by_key`, and -:func:`memcached_decrement_with_initial_by_key` are master key equivalents of the above. - -RETURN ------- - -A value of type :type:`memcached_return_t` is returned. +`memcached_increment` takes a ``key`` and ``key_length`` and increments the +value by the ``offset`` passed to it. The value is then returned via the +uint32_t ``value`` pointer you pass to it. + +`memcached_decrement` takes a ``key`` and ``key_length`` and decrements the +value by the ``offset`` passed to it. The value is then returned via the +uint32_t ``value`` pointer you pass to it. + +`memcached_increment_with_initial` takes a ``key`` and ``key_length`` and +increments the value by the ``offset`` passed to it. If the object specified by +``key`` does not exist, one of two things may happen: If the ``expiration`` +value is :c:macro:`MEMCACHED_EXPIRATION_NOT_ADD`, the operation will fail. For +all other ``expiration`` values, the operation will succeed by seeding the value +for that key with a initial value to expire with the provided expiration time. +The ``flags`` will be set to zero. The value is then returned via the uint32_t +``value`` pointer you pass to it. ``memcached_increment_with_initial`` is only +available when using the binary protocol. + +`memcached_decrement_with_initial` takes a ``key`` and ``key_length`` and +decrements the value by the ``offset`` passed to it. If the object specified by +``key`` does not exist, one of two things may happen: If the ``expiration`` +value is :c:macro:`MEMCACHED_EXPIRATION_NOT_ADD`, the operation will fail. For +all other ``expiration`` values, the operation will succeed by seeding the value +for that key with a initial value to expire with the provided expiration time. +The ``flags`` will be set to zero. The value is then returned via the uint32_t +``value`` pointer you pass to it. `memcached_decrement_with_initial` is only +available when using the binary protocol. + +`memcached_increment_by_key`, `memcached_decrement_by_key`, +`memcached_increment_with_initial_by_key`, and +`memcached_decrement_with_initial_by_key` are master key equivalents of the +above. + +RETURN VALUE +------------ + +A value of 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. +Use `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(1)` + :manpage:`libmemcached(3)` + :manpage:`memcached_strerror(3)` + +.. only:: html + + * :manpage:`memcached(1)` + * :doc:`../libmemcached` + * :doc:`memcached_strerror` diff --git a/docs/source/libmemcached/memcached_behavior.rst b/docs/source/libmemcached/memcached_behavior.rst index 0730230d..bd9998a3 100644 --- a/docs/source/libmemcached/memcached_behavior.rst +++ b/docs/source/libmemcached/memcached_behavior.rst @@ -11,17 +11,15 @@ SYNOPSIS #include Compile and link with -lmemcached -.. c:type:: typedef enum memcached_behavior_t memcached_behavior_t; - .. function:: uint64_t memcached_behavior_get (memcached_st *ptr, memcached_behavior_t flag) .. function:: memcached_return_t memcached_behavior_set (memcached_st *ptr, memcached_behavior_t flag, uint64_t data) .. versionchanged:: 0.17 - The `data` argument of :func:`memcached_behavior_set` was changed in + The `data` argument of `memcached_behavior_set` was changed in from taking a pointer to data value, to taking a uin64_t. -.. c:type:: enum memcached_behavior_t memcached_behavior_t +.. type:: enum memcached_behavior_t memcached_behavior_t .. enum:: memcached_behavior_t @@ -34,15 +32,15 @@ SYNOPSIS The following operations will return `MEMCACHED_NOT_SUPPORTED` when executed with `MEMCACHED_BEHAVIOR_USE_UDP` enabled: - * :func:`memcached_version`, - * :func:`memcached_stat`, - * :func:`memcached_get`, - * :func:`memcached_get_by_key`, - * :func:`memcached_mget`, - * :func:`memcached_mget_by_key`, - * :func:`memcached_fetch`, - * :func:`memcached_fetch_result`, - * :func:`memcached_fetch_execute`. + * `memcached_version`, + * `memcached_stat`, + * `memcached_get`, + * `memcached_get_by_key`, + * `memcached_mget`, + * `memcached_mget_by_key`, + * `memcached_fetch`, + * `memcached_fetch_result`, + * `memcached_fetch_execute`. All other operations are tested but are executed in a 'fire-and-forget' mode, in which once the client has executed the operation, no attempt @@ -117,8 +115,8 @@ SYNOPSIS distribution and allows servers to be added to the cluster with minimal cache losses. - Currently `MEMCACHED_DISTRIBUTION_CONSISTENT` is an alias for the - value type:`MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA`. + Currently `MEMCACHED_DISTRIBUTION_CONSISTENT` is an alias for the value + `MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA`. .. enumerator:: MEMCACHED_BEHAVIOR_CACHE_LOOKUPS @@ -143,7 +141,7 @@ SYNOPSIS Sets the default distribution to `MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA` with the weighted tests. - Makes the default hashing algorithm for keys use MD5. + Makes the default hashing algorithm for keys use `MEMCACHED_HASH_MD5`. .. enumerator:: MEMCACHED_BEHAVIOR_KETAMA_HASH @@ -220,9 +218,9 @@ SYNOPSIS `libmemcached` should start to automatically drain the input queue (need at least 10 IO requests sent without reading the input buffer). - Setting this value to high, may cause libmemcached to deadlock (trying to - send data, but the send will block because the input buffer in the kernel - is full). + Setting this value to high, may cause libmemcached to deadlock (trying + to send data, but the send will block because the input buffer in the + kernel is full). .. enumerator:: MEMCACHED_BEHAVIOR_IO_KEY_PREFETCH @@ -264,8 +262,8 @@ SYNOPSIS .. enumerator:: MEMCACHED_BEHAVIOR_CORK .. deprecated:: ? - This open has been deprecated with the behavior now built and used - appropriately on selected platforms. + This option has been deprecated with the behavior now built in and + used appropriately on selected platforms. .. enumerator:: MEMCACHED_BEHAVIOR_KEEPALIVE @@ -331,30 +329,30 @@ SYNOPSIS DESCRIPTION ----------- -`libmemcached` behavior can be modified by using :func:`memcached_behavior_set`. +`libmemcached` behavior can be modified by using `memcached_behavior_set`. Default behavior is the library strives to be quick and accurate. Some behavior, while being faster, can also result in not entirely accurate behavior (for -instance, :func:`memcached_set` will always respond with `MEMCACHED_SUCCESS`). +instance, `memcached_set` will always respond with `MEMCACHED_SUCCESS`). -:func:`memcached_behavior_get` takes a behavior flag and returns whether or not +`memcached_behavior_get` takes a behavior ``flag`` and returns whether or not that behavior is currently enabled in the client. -:func:`memcached_behavior_set` changes the value of a particular option of the -client. It takes both a flag (listed below) and a value. For simple on or off -options you just need to pass in a value of 1. Calls to -:func:`memcached_behavior_set` will flush and reset all connections. +`memcached_behavior_set` changes the value of a particular option of the client. +It takes both a ``flag`` and a ``value``. For simple on or off options you just +need to pass in a value of 1. Calls to `memcached_behavior_set` will flush and +reset all connections. RETURN VALUE ------------ -:func:`memcached_behavior_get` returns either the current value of the key, or 0 -or 1 on simple flag behaviors (1 being enabled). :func:`memcached_behavior_set` +`memcached_behavior_get` returns either the current value of the key, or 0 +or 1 on simple flag behaviors (1 being enabled). `memcached_behavior_set` returns failure or success. NOTES ----- -The `data` argument of :func:`memcached_behavior_set` was changed in version +The `data` argument of `memcached_behavior_set` was changed in version 0.17 from taking a pointer to data value, to taking a uin64_t. SEE ALSO diff --git a/docs/source/libmemcached/memcached_callback.rst b/docs/source/libmemcached/memcached_callback.rst index e0158f6f..805f21a9 100644 --- a/docs/source/libmemcached/memcached_callback.rst +++ b/docs/source/libmemcached/memcached_callback.rst @@ -1,10 +1,6 @@ -Setting callbacks +Library callbacks ================= -Get and set a callback - -.. index:: object: memcached_st - SYNOPSIS -------- @@ -15,19 +11,19 @@ SYNOPSIS .. function:: void *memcached_callback_get(memcached_st *ptr, memcached_callback_t flag, memcached_return_t *error) -.. c:type:: enum memcached_callback_t memcached_callback_t +.. type:: enum memcached_callback_t memcached_callback_t .. enum:: memcached_callback_t .. enumerator:: MEMCACHED_CALLBACK_CLEANUP_FUNCTION - When :func:`memcached_delete` is called this function will be executed. At - the point of its execution all connections are closed. + When `memcached_delete` is called this function will be executed. At the + point of its execution all connections are closed. .. enumerator:: MEMCACHED_CALLBACK_CLONE_FUNCTION - When :func:`memcached_delete` is called this function will be executed. - At the point of its execution all connections are closed. + When `memcached_delete` is called this function will be executed. At the + point of its execution all connections are closed. .. enumerator:: MEMCACHED_CALLBACK_PREFIX_KEY @@ -36,49 +32,52 @@ SYNOPSIS .. enumerator:: MEMCACHED_CALLBACK_NAMESPACE 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 value specified here will be prefixed to each of your keys. The + value can not be greater then :c:macro:`MEMCACHED_MAX_NAMESPACE` - 1 and + will reduce :c:macro:`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. + `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. .. enumerator:: MEMCACHED_CALLBACK_USER_DATA - This allows you to store a pointer to a specific piece of data. This can be - retrieved from inside of :func:`memcached_fetch_execute`. Cloning a - :type:`memcached_st` will copy the pointer to the clone. + This allows you to store a pointer to a specific piece of data. This can + be retrieved from inside of `memcached_fetch_execute`. Cloning a + `memcached_st` will copy the pointer to the clone. .. enumerator:: MEMCACHED_CALLBACK_MALLOC_FUNCTION .. deprecated:: <0.32 - Use :type:`memcached_set_memory_allocators` instead. + Use `memcached_set_memory_allocators` instead. .. enumerator:: MEMCACHED_CALLBACK_REALLOC_FUNCTION .. deprecated:: <0.32 - Use :type:`memcached_set_memory_allocators` instead. + Use `memcached_set_memory_allocators` instead. .. enumerator:: MEMCACHED_CALLBACK_FREE_FUNCTION .. deprecated:: <0.32 - Use :type:`memcached_set_memory_allocators` instead. + Use `memcached_set_memory_allocators` instead. .. enumerator:: 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 :type:`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 - immediately (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 immediately (if this is the default + behavior based on your connection setup this will happen automatically). The prototype for this is: @@ -86,7 +85,9 @@ SYNOPSIS .. enumerator:: MEMCACHED_CALLBACK_DELETE_TRIGGER - This function implements a trigger upon successful deletion of a key. The memcached_st structure will need to be cloned in order to make use of it. + This function implements a trigger upon successful deletion of a key. + The `memcached_st` structure will need to be cloned in order to make use + of it. The prototype for this is: @@ -95,32 +96,40 @@ SYNOPSIS DESCRIPTION ----------- -`libmemcached` can have callbacks set key execution points. These either -provide function calls at points in the code, or return pointers to -structures for particular usages. +`libmemcached` can have callbacks set key execution points. These either provide +function calls at points in the code, or return pointers to structures for +particular usages. -:func:`memcached_callback_get` takes a callback flag and returns the -structure or function set by :func:`memcached_callback_set`. +`memcached_callback_get` takes a callback flag and returns the structure or +function set by `memcached_callback_set`. -:func:`memcached_callback_set` changes the function/structure assigned by a -callback flag. No connections are reset. +`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. RETURN VALUE ------------ -:func:`memcached_callback_get` return the function or structure that was -provided. Upon error, nothing is set, null is returned, and the -:type:`memcached_return_t` argument is set to `MEMCACHED_FAILURE`. +`memcached_callback_get` returns the function or structure that was provided. +Upon error, nothing is set, NULL is returned, and the `memcached_return_t` +argument is set to `MEMCACHED_FAILURE`. -:func:`memcached_callback_set` returns `MEMCACHED_SUCCESS` upon -successful setting, otherwise `MEMCACHED_FAILURE` on error. +`memcached_callback_set` returns `MEMCACHED_SUCCESS` upon successful setting, +otherwise `MEMCACHED_FAILURE` on error. SEE ALSO -------- .. only:: man - :manpage:`memcached(1)` :manpage:`libmemcached(3)` :manpage:`memcached_strerror(3)` + :manpage:`memcached(1)` + :manpage:`libmemcached(3)` + :manpage:`memcached_strerror(3)` + +.. only:: html + + * :manpage:`memcached(1)` + * :doc:`../libmemcached` + * :doc:`memcached_strerror` diff --git a/docs/source/libmemcached/memcached_cas.rst b/docs/source/libmemcached/memcached_cas.rst index aec7ef46..017c658f 100644 --- a/docs/source/libmemcached/memcached_cas.rst +++ b/docs/source/libmemcached/memcached_cas.rst @@ -1,54 +1,56 @@ Working with data on the server in an atomic fashion ==================================================== -.. index:: object: memcached_st - SYNOPSIS -------- #include + Compile and link with -lmemcached .. 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) .. function:: memcached_return_t memcached_cas_by_key(memcached_st *ptr, const char *group_key, size_t group_key_length, const char *key, size_t key_length, const char *value, size_t value_length, time_t expiration, uint32_t flags, uint64_t cas) -Compile and link with -lmemcached DESCRIPTION ----------- -: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 -key methods. The difference is that it uses the group_key parameter -to map objects to particular servers. - -:func:`memcached_cas` is tested 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 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. - -RETURN ------- - -All methods return a value of type :type:`memcached_return_t`. +`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 `memcached_result_cas` on a `memcached_result_st` structure. + +At the point that this note was written cas is still buggy in memcached. Turning +on tests for it in `libmemcached` is optional. Please see `memcached_set` for +information on how to do this. + +`memcached_cas_by_key` method behaves in a similar way as the non key methods. +The difference is that it uses the ``group_key`` parameter to map objects to +particular servers. + +`memcached_cas` is tested 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 +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. + +RETURN VALUE +------------ + +All methods return a value of type `memcached_return_t`. On success the value will be `MEMCACHED_SUCCESS`. -Use :func:`memcached_strerror` to translate this value to a printable +Use `memcached_strerror` to translate this value to a printable string. SEE ALSO @@ -56,5 +58,19 @@ SEE ALSO .. only:: man - :manpage:`memcached(1)` :manpage:`libmemcached(3)` :manpage:`memcached_strerror(3)` :manpage:`memcached_set(3)` :manpage:`memcached_append(3)` :manpage:`memcached_add(3)` :manpage:`memcached_prepend(3)` :manpage:`memcached_replace(3)` - + :manpage:`memcached(1)` + :manpage:`libmemcached(3)` + :manpage:`memcached_strerror(3)` + :manpage:`memcached_set(3)` + :manpage:`memcached_append(3)` + :manpage:`memcached_add(3)` + :manpage:`memcached_prepend(3)` + :manpage:`memcached_replace(3)` + +.. only:: html + + * :manpage:`memcached(1)` + * :doc:`../libmemcached` + * :doc:`memcached_set` + * :doc:`memcached_append` + * :doc:`memcached_strerror` diff --git a/docs/source/libmemcached/memcached_create.rst b/docs/source/libmemcached/memcached_create.rst index 1189fdf0..a5bc6379 100644 --- a/docs/source/libmemcached/memcached_create.rst +++ b/docs/source/libmemcached/memcached_create.rst @@ -5,8 +5,9 @@ SYNOPSIS -------- #include + Compile and link with -lmemcached -.. type:: memcached_st +.. type:: struct memcached_st memcached_st .. function:: memcached_st* memcached_create(memcached_st *ptr) @@ -16,51 +17,52 @@ SYNOPSIS .. function:: void memcached_servers_reset(memcached_st) -Compile and link with -lmemcached - DESCRIPTION ----------- -: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 +`memcached_create` is used to create a `memcached_st` structure that will then +be used by other `libmemcached` functions to communicate with the server. You +should either pass a statically declared `memcached_st` to `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 -:func:`memcached` over :func:`memcached_create`. +Please note, when you write new application use `memcached` over +`memcached_create`. -: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. +`memcached_clone` is similar to `memcached_create` but it copies the defaults +and list of servers from the source `memcached_st`. If you pass a null as the +argument for the source to clone, it is the same as a call to +`memcached_create`. If the destination argument is NULL a `memcached_st` will be +allocated for you. -:func:`memcached_servers_reset` allows you to zero out the list of -servers that the :type:`memcached_st` has. +`memcached_servers_reset` allows you to zero out the list of servers that the +`memcached_st` has. -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. +To clean up memory associated with a `memcached_st` structure you should pass it +to `memcached_free` when you are finished using it. `memcached_free` is the only +way to make sure all memory is deallocated when you finish using the structure. -You may wish to avoid using memcached_create(3) or memcached_clone(3) with a -stack based allocation. The most common issues related to ABI safety involve -heap allocated structures. +You may wish to avoid using `memcached_create` or `memcached_clone` with a stack +based allocation. The most common issues related to ABI safety involve heap +allocated structures. -RETURN ------- +RETURN VALUE +------------ -:func:`memcached_create` returns a pointer to the :type:`memcached_st` -that was created (or initialized). On an allocation failure, it returns NULL. +`memcached_create` returns a pointer to the `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` -that was created (or initialized). On an allocation failure, it returns NULL. +`memcached_clone` returns a pointer to the `memcached_st` that was created (or +initialized). On an allocation failure, it returns NULL. SEE ALSO -------- .. only:: man - :manpage:`memcached(1)` :manpage:`libmemcached(3)` :manpage:`memcached_strerror(3)` + :manpage:`memcached(1)` + :manpage:`libmemcached(3)` + +.. only:: html + + * :manpage:`memcached(1)` + * :doc:`../libmemcached` diff --git a/docs/source/libmemcached/memcached_delete.rst b/docs/source/libmemcached/memcached_delete.rst index 767e01b4..f3763090 100644 --- a/docs/source/libmemcached/memcached_delete.rst +++ b/docs/source/libmemcached/memcached_delete.rst @@ -1,48 +1,52 @@ Deleting data from a server =========================== -.. index:: object: memcached_st - SYNOPSIS -------- #include + Compile and link with -lmemcached .. 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_by_key` works the same, but it takes a master key -to find the given value. +`memcached_delete` is used to delete a particular key. `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 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. +Expiration works by placing the item into a delete queue, which means that 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 memcached server removed tests for expiration in -the 1.4 version. +Please note the the memcached server removed tests for expiration in the 1.4 +version. -RETURN ------- +RETURN VALUE +------------ -A value of type :type:`memcached_return_t` is returned +A value of 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. +Use `memcached_strerror` to translate this value to a printable string. -If you are using the non-blocking mode of the library, success only -means that the message was queued for delivery. +If you are using the non-blocking mode of the library, success only means that +the message was queued for delivery. SEE ALSO -------- .. only:: man - :manpage:`memcached(1)` :manpage:`libmemcached(3)` :manpage:`memcached_strerror(3)` + :manpage:`memcached(1)` + :manpage:`libmemcached(3)` + :manpage:`memcached_strerror(3)` + +.. only:: html + + * :manpage:`memcached(1)` + * :doc:`../libmemcached` + * :doc:`memcached_strerror` diff --git a/docs/source/libmemcached/memcached_dump.rst b/docs/source/libmemcached/memcached_dump.rst index e0c419f7..ec0de8a7 100644 --- a/docs/source/libmemcached/memcached_dump.rst +++ b/docs/source/libmemcached/memcached_dump.rst @@ -26,8 +26,8 @@ of callbacks that it will use to execute on keys as they are found. Currently the binary protocol is not tested. -RETURN ------- +RETURN VALUE +------------ A value of type :type:`memcached_return_t` is returned On success that value will be `MEMCACHED_SUCCESS`. diff --git a/docs/source/libmemcached/memcached_exist.rst b/docs/source/libmemcached/memcached_exist.rst index 099eda2a..60f5ae2a 100644 --- a/docs/source/libmemcached/memcached_exist.rst +++ b/docs/source/libmemcached/memcached_exist.rst @@ -22,8 +22,8 @@ DESCRIPTION :func:`memcached_exist()` can be used to check if a key exists. -RETURN ------- +RETURN VALUE +------------ `MEMCACHED_SUCCESS` The key exists. diff --git a/docs/source/libmemcached/memcached_fetch.rst b/docs/source/libmemcached/memcached_fetch.rst index 0e9378d9..ae567777 100644 --- a/docs/source/libmemcached/memcached_fetch.rst +++ b/docs/source/libmemcached/memcached_fetch.rst @@ -31,8 +31,8 @@ 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 ------- +RETURN VALUE +------------ :func:`memcached_fetch` sets error to to `MEMCACHED_END` upon successful conclusion. diff --git a/docs/source/libmemcached/memcached_flush.rst b/docs/source/libmemcached/memcached_flush.rst index 071a989f..52addbb3 100644 --- a/docs/source/libmemcached/memcached_flush.rst +++ b/docs/source/libmemcached/memcached_flush.rst @@ -24,8 +24,8 @@ 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 ------- +RETURN VALUE +------------ A value of type :type:`memcached_return_t` is returned On success that value will be `MEMCACHED_SUCCESS`. diff --git a/docs/source/libmemcached/memcached_flush_buffers.rst b/docs/source/libmemcached/memcached_flush_buffers.rst index 45f9a9a7..9e71fb21 100644 --- a/docs/source/libmemcached/memcached_flush_buffers.rst +++ b/docs/source/libmemcached/memcached_flush_buffers.rst @@ -20,8 +20,8 @@ DESCRIPTION :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 ------- +RETURN VALUE +------------ A value of type :type:`memcached_return_t` is returned On success that value will be `MEMCACHED_SUCCESS`. diff --git a/docs/source/libmemcached/memcached_generate_hash_value.rst b/docs/source/libmemcached/memcached_generate_hash_value.rst index 9c84be7e..2c72cbbc 100644 --- a/docs/source/libmemcached/memcached_generate_hash_value.rst +++ b/docs/source/libmemcached/memcached_generate_hash_value.rst @@ -58,8 +58,8 @@ 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 ------- +RETURN VALUE +------------ 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 diff --git a/docs/source/libmemcached/memcached_get.rst b/docs/source/libmemcached/memcached_get.rst index 49b11ab3..cb4415a2 100644 --- a/docs/source/libmemcached/memcached_get.rst +++ b/docs/source/libmemcached/memcached_get.rst @@ -89,8 +89,8 @@ 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 ------- +RETURN VALUE +------------ All objects retrieved via :func:`memcached_get` or :func:`memcached_get_by_key` must be freed with :manpage:`free(3)`. diff --git a/docs/source/libmemcached/memcached_memory_allocators.rst b/docs/source/libmemcached/memcached_memory_allocators.rst index 760f3d07..9f8f98fd 100644 --- a/docs/source/libmemcached/memcached_memory_allocators.rst +++ b/docs/source/libmemcached/memcached_memory_allocators.rst @@ -54,8 +54,8 @@ 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 ------- +RETURN VALUE +------------ :func:`memcached_set_memory_allocators` return `MEMCACHED_SUCCESS` upon success, and `MEMCACHED_FAILURE` if you don't pass a complete set of function pointers. diff --git a/docs/source/libmemcached/memcached_quit.rst b/docs/source/libmemcached/memcached_quit.rst index 6559a7c4..60e11ae7 100644 --- a/docs/source/libmemcached/memcached_quit.rst +++ b/docs/source/libmemcached/memcached_quit.rst @@ -24,8 +24,8 @@ 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 ------- +RETURN VALUE +------------ A value of type :type:`memcached_return_t` is returned On success that value will be `MEMCACHED_SUCCESS`. Use :func:`memcached_strerror` to diff --git a/docs/source/libmemcached/memcached_result_st.rst b/docs/source/libmemcached/memcached_result_st.rst index 67fd304f..fcc00abe 100644 --- a/docs/source/libmemcached/memcached_result_st.rst +++ b/docs/source/libmemcached/memcached_result_st.rst @@ -92,8 +92,8 @@ 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 ------- +RETURN VALUE +------------ Varies, see particular functions. All structures must have :func:`memcached_result_free` called on them for cleanup purposes. Failure diff --git a/docs/source/libmemcached/memcached_sasl.rst b/docs/source/libmemcached/memcached_sasl.rst index 3be3f2b6..e87451ae 100644 --- a/docs/source/libmemcached/memcached_sasl.rst +++ b/docs/source/libmemcached/memcached_sasl.rst @@ -35,8 +35,8 @@ 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 ------- +RETURN VALUE +------------ :func:`memcached_get_sasl_callbacks` returns the callbacks currently used by this memcached handle. :func:`memcached_set_sasl_auth_data` returns diff --git a/docs/source/libmemcached/memcached_server_st.rst b/docs/source/libmemcached/memcached_server_st.rst index 9cc23929..faa7c4c9 100644 --- a/docs/source/libmemcached/memcached_server_st.rst +++ b/docs/source/libmemcached/memcached_server_st.rst @@ -55,8 +55,8 @@ DEPRECATED :func:`memcached_servers_parse`, please see :func:`memcached` Before version 0.39 theses functions used a memcached_server_st \*. In 0.39 memcached_server_st \* was aliased to :type:`memcached_server_list_st`. This was done for a style reason to help clean up some concepts in the code. -RETURN ------- +RETURN VALUE +------------ Varies, see particular functions. diff --git a/docs/source/libmemcached/memcached_servers.rst b/docs/source/libmemcached/memcached_servers.rst index aef224a5..ebac5fbc 100644 --- a/docs/source/libmemcached/memcached_servers.rst +++ b/docs/source/libmemcached/memcached_servers.rst @@ -67,8 +67,8 @@ 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 ------- +RETURN VALUE +------------ Varies, see particular functions. diff --git a/docs/source/libmemcached/memcached_set_encoding_key.rst b/docs/source/libmemcached/memcached_set_encoding_key.rst index 86721342..38ddba09 100644 --- a/docs/source/libmemcached/memcached_set_encoding_key.rst +++ b/docs/source/libmemcached/memcached_set_encoding_key.rst @@ -19,8 +19,8 @@ DESCRIPTION Currently only AES is is supported. -RETURN ------- +RETURN VALUE +------------ A value of type :type:`memcached_return_t` is returned On success that value will be `MEMCACHED_SUCCESS`. Use :func:`memcached_strerror` to diff --git a/docs/source/libmemcached/memcached_stats.rst b/docs/source/libmemcached/memcached_stats.rst index 92a0308c..496b06b6 100644 --- a/docs/source/libmemcached/memcached_stats.rst +++ b/docs/source/libmemcached/memcached_stats.rst @@ -49,8 +49,8 @@ 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 ------- +RETURN VALUE +------------ Varies, see particular functions. diff --git a/docs/source/libmemcached/memcached_strerror.rst b/docs/source/libmemcached/memcached_strerror.rst index 32b0b7b2..09ed37e9 100644 --- a/docs/source/libmemcached/memcached_strerror.rst +++ b/docs/source/libmemcached/memcached_strerror.rst @@ -23,8 +23,8 @@ functions. `memcached_return_t` values are of an enum type so that you can set up responses with switch/case and know that you are capturing all possible return values. -RETURN ------- +RETURN VALUE +------------ `memcached_strerror` returns a string describing a `memcached_return_t` value. diff --git a/docs/source/libmemcached/memcached_touch.rst b/docs/source/libmemcached/memcached_touch.rst index 05c68790..b1b982e4 100644 --- a/docs/source/libmemcached/memcached_touch.rst +++ b/docs/source/libmemcached/memcached_touch.rst @@ -22,8 +22,8 @@ DESCRIPTION :func:`memcached_touch_by_key` works the same, but it takes a master key to find the given value. -RETURN ------- +RETURN VALUE +------------ A value of type :type:`memcached_return_t` is returned On success that value will be `MEMCACHED_SUCCESS`. diff --git a/docs/source/libmemcached/memcached_user_data.rst b/docs/source/libmemcached/memcached_user_data.rst index c830a16b..a0437df3 100644 --- a/docs/source/libmemcached/memcached_user_data.rst +++ b/docs/source/libmemcached/memcached_user_data.rst @@ -33,8 +33,8 @@ the memcached_st structure. :func:`memcached_get_user_data` is used to retrieve the user specific data in the :type:`memcached_st` structure. -RETURN ------- +RETURN VALUE +------------ :func:`memcached_set_user_data` returns the previous value of the user specific data. diff --git a/docs/source/libmemcached/memcached_verbosity.rst b/docs/source/libmemcached/memcached_verbosity.rst index db7aee16..cf9db0e7 100644 --- a/docs/source/libmemcached/memcached_verbosity.rst +++ b/docs/source/libmemcached/memcached_verbosity.rst @@ -20,8 +20,8 @@ DESCRIPTION :func:`memcached_verbosity` modifies the "verbosity" of the memcached(1) servers referenced in the :type:`memcached_st` parameter. -RETURN ------- +RETURN VALUE +------------ A value of type :type:`memcached_return_t` is returned. diff --git a/docs/source/libmemcached/memcached_version.rst b/docs/source/libmemcached/memcached_version.rst index 6acb6c59..e11c8334 100644 --- a/docs/source/libmemcached/memcached_version.rst +++ b/docs/source/libmemcached/memcached_version.rst @@ -19,8 +19,8 @@ DESCRIPTION :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 ------- +RETURN VALUE +------------ :func:`memcached_lib_version` returns a string with the version of the libmemcached driver. diff --git a/docs/source/libmemcachedutil.rst b/docs/source/libmemcachedutil.rst index 369600ce..fb2e994d 100644 --- a/docs/source/libmemcachedutil.rst +++ b/docs/source/libmemcachedutil.rst @@ -13,16 +13,16 @@ SYNOPSIS DESCRIPTION ----------- -`libmemcachedutil` is a small and thread-safe client library that -provides extra functionality built on top of `libmemcached`. +`libmemcachedutil` is a small and thread-safe client library that provides extra +functionality built on top of `libmemcached`. -THREADS -------- +THREADS AND PROCESSES +--------------------- -Do not try to access an instance of :type:`memcached_st` from multiple threads -at the same time. If you want to access memcached from multiple threads -you should either clone the :type:`memcached_st`, or use the memcached pool -implementation. See :func:`memcached_pool_create`. +Do not try to access an instance of `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`. SEE ALSO -------- diff --git a/docs/source/libmemcachedutil/memcached_pool.rst b/docs/source/libmemcachedutil/memcached_pool.rst index 0da28203..d089147b 100644 --- a/docs/source/libmemcachedutil/memcached_pool.rst +++ b/docs/source/libmemcachedutil/memcached_pool.rst @@ -4,7 +4,7 @@ Working with memcached pools SYNOPSIS -------- -#include +#include Compile and link with -lmemcachedutil -lmemcached .. type:: struct memcached_pool_st memcached_pool_st @@ -14,72 +14,75 @@ SYNOPSIS .. 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 + + .. versionadded:: 0.53 + Synonym for memcached_pool_pop .. function:: memcached_return_t memcached_pool_release(memcached_pool_st* pool, memcached_st* mmc) -.. versionadded:: 0.53 - Synonym for memcached_pool_push. + + .. 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_pool_st* memcached_pool_create(memcached_st* mmc, int initial, int max) -.. deprecated:: 0.46 - Use :func:`memcached_pool` + + .. deprecated:: 0.46 + Use `memcached_pool` .. function:: memcached_st* memcached_pool_pop(memcached_pool_st* pool, bool block, memcached_return_t *rc) -.. deprecated:: 0.53 - Use :func:`memcached_pool_fetch` + + .. deprecated:: 0.53 + Use `memcached_pool_fetch` .. function:: memcached_return_t memcached_pool_push(memcached_pool_st* pool, memcached_st *mmc) -.. deprecated:: 0.53 - Use :func:`memcached_pool_release` + + .. deprecated:: 0.53 + Use `memcached_pool_release` DESCRIPTION ----------- -: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. +`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 `memcached_st` +objects. Please see :doc:`../libmemcached/configuration` for details on the +format of the configuration string. -:func:`memcached_pool_destroy` is used to destroy the connection pool -created with :func:`memcached_pool_create` and release all allocated -resources. It will return the pointer to the :type:`memcached_st` structure -passed as an argument to :func:`memcached_pool_create`, and returns the -ownership of the pointer to the caller when created with -:func:`memcached_pool_create`, otherwise NULL is returned.. +`memcached_pool_destroy` is used to destroy the connection pool created with +`memcached_pool_create` and release all allocated resources. It will return the +pointer to the `memcached_st` structure passed as an argument to +`memcached_pool_create`, and returns the ownership of the pointer to the caller +when created with `memcached_pool_create`, otherwise NULL is returned.. -:func:`memcached_pool_fetch` is used to fetch a connection structure from the +`memcached_pool_fetch` is used to fetch a connection structure from the connection pool. The relative_time argument specifies if the function should -block and wait for a connection structure to be available if we try -to exceed the maximum size. You need to specify time in relative time. +block and wait for a connection structure to be available if we try to exceed +the maximum size. You need to specify time in relative time. -:func:`memcached_pool_release` is used to return a connection structure back -to the pool. +`memcached_pool_release` is used to return a connection structure back to the +pool. -:func:`memcached_pool_behavior_get` and :func:`memcached_pool_behavior_set` -is used to get/set behavior flags on all connections in the pool. +`memcached_pool_behavior_get` and `memcached_pool_behavior_set` 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. +Both `memcached_pool_release` and `memcached_pool_fetch` are thread safe. -RETURN ------- +RETURN VALUE +------------ -:func:`memcached_pool_destroy` returns the pointer (and ownership) to the -:type:`memcached_st` structure used to create the pool. If connections are in -use it returns NULL. +`memcached_pool_destroy` returns the pointer (and ownership) to the +`memcached_st` structure used to create the pool. If connections are in use it +returns NULL. -:func:`memcached_pool_pop` returns a pointer to a :type:`memcached_st` -structure from the pool (or NULL if an allocation cannot be satisfied). +`memcached_pool_pop` returns a pointer to a `memcached_st` structure from the +pool (or NULL if an allocation cannot be satisfied). -:func:`memcached_pool_release` returns `MEMCACHED_SUCCESS` upon success. +`memcached_pool_release` returns `MEMCACHED_SUCCESS` upon success. -:func:`memcached_pool_behavior_get` and :func:`memcached_pool_behavior_get` -returns `MEMCACHED_SUCCESS` upon success. +`memcached_pool_behavior_get` and `memcached_pool_behavior_get` returns +`MEMCACHED_SUCCESS` upon success. If any methods returns MEMCACHED_IN_PROGRESS then a lock on the pool could not be obtained. If any of the parameters passed to any of these functions is