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"
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")
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/
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>
libmemcached/index
:hidden:
copyright
+
+Index
+-----
+
+:ref:`genindex`
Creating a hashkit structure
============================
-Create, copy and free a hashkit structure
-
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
--------
Set Hash Function
=================
-.. index:: object: hashkit_st
-.. index:: object: hashkit_hash_fn
-
-Set hash functions to use for calculating values for keys
-
SYNOPSIS
--------
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
--------
Available Hashes
================
-.. index:: object: hashkit_st
-
-Various hash functions to use for calculating hash values for keys
-
SYNOPSIS
--------
Generate hash value
===================
-.. index:: object: hashkit_st
-
-Generate a value for the given key
-
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
------------
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/ <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/ <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
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
---------
SYNOPSIS
--------
-#include <libmemcached-1.0/memcached.h>
+#include <libmemcached-|libmemcached_version|/memcached.h>
Compile and link with -lmemcached
.. function:: memcached_st *memcached(const char *string, size_t string_length)
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=\"<filepath>/?<optional_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
+ 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
.. 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
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
-------
SYNOPSIS
--------
-#include <libmemcached-1.0/memcached.h>
+#include <libmemcached-|libmemcached_version|/memcached.h>
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
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.
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
---------------------
}
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));
*/
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
index_deprecated
.. toctree:
- :titlesonlx:
+ :titlesonly:
:caption: Misc
index_misc
Analyzing servers
=================
-Analyze server information
-
SYNOPSIS
--------
-.. index:: object: memcached_analysis_st
-
#include <libmemcached/memcached.h>
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
--------
-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 <libmemcached/memcached.h>
+#include <libmemcached-|libmemcached_version|/memcached.h>
+ 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)
.. 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`
Incrementing and Decrementing Values
====================================
-.. index:: object: memcached_st
-
SYNOPSIS
--------
#include <libmemcached/memcached.h>
+ 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)
.. 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
-----------
(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`
#include <libmemcached/memcached.h>
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
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
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
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
`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
.. 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
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
-Setting callbacks
+Library callbacks
=================
-Get and set a callback
-
-.. index:: object: memcached_st
-
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
.. 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:
.. 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:
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`
Working with data on the server in an atomic fashion
====================================================
-.. index:: object: memcached_st
-
SYNOPSIS
--------
#include <libmemcached/memcached.h>
+ 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
.. 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`
--------
#include <libmemcached/memcached.h>
+ Compile and link with -lmemcached
-.. type:: memcached_st
+.. type:: struct memcached_st memcached_st
.. function:: memcached_st* memcached_create(memcached_st *ptr)
.. 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`
Deleting data from a server
===========================
-.. index:: object: memcached_st
-
SYNOPSIS
--------
#include <libmemcached/memcached.h>
+ 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`
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`.
:func:`memcached_exist()` can be used to check if a key exists.
-RETURN
-------
+RETURN VALUE
+------------
`MEMCACHED_SUCCESS`
The key exists.
`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.
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`.
: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`.
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
`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)`.
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.
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
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
: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
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.
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.
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
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.
`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.
: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`.
: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.
: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.
: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.
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
--------
SYNOPSIS
--------
-#include <libmemcached/memcached_pool.h>
+#include <libmemcachedutil-|libmemcached_version|/pool.h>
Compile and link with -lmemcachedutil -lmemcached
.. type:: struct memcached_pool_st memcached_pool_st
.. 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
projects / awesomized / libmemcached / commitdiff
