Manipulate the behavior of a memcached_st structure.
-.. index:: object: memcached_st
-
SYNOPSIS
--------
#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)
+ :param ptr: pointer to initialized `memcached_st` struct
+ :param flag: `memcached_behavior_t` to query
+ :returns: the vaue set for `flag`
+
.. function:: memcached_return_t memcached_behavior_set (memcached_st *ptr, memcached_behavior_t flag, uint64_t data)
+ :param ptr: pointer to initialized `memcached_st` struct
+ :param flag: `memcached_behavior_t` to set
+ :param data: the value to set for `flag`
+ :returns: `memcached_return_t` indicating success
+
.. versionchanged:: 0.17
- The `data` argument of :func:`memcached_behavior_set` was changed in
+ The `data` argument of `memcached_behavior_set` was changed
from taking a pointer to data value, to taking a uin64_t.
.. c:type:: enum memcached_behavior_t 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
.. enumerator:: MEMCACHED_BEHAVIOR_TCP_NODELAY
- Turns on the no-delay feature for connecting sockets (may be faster in
- some environments).
+ Disables Nagle's algorithm.
+ See `RFC 896 <https://tools.ietf.org/html/rfc896>`_.
.. enumerator:: MEMCACHED_BEHAVIOR_HASH
- Set the hash algorithm used for keys.
-
- The value can be set to either:
-
- * `MEMCACHED_HASH_DEFAULT`,
- * `MEMCACHED_HASH_MD5`,
- * `MEMCACHED_HASH_CRC`,
- * `MEMCACHED_HASH_FNV1_64`,
- * `MEMCACHED_HASH_FNV1A_64`,
- * `MEMCACHED_HASH_FNV1_32`,
- * `MEMCACHED_HASH_FNV1A_32`,
- * `MEMCACHED_HASH_JENKINS`,
- * `MEMCACHED_HASH_HSIEH`, and
- * `MEMCACHED_HASH_MURMUR`.
+ Set the `hash algorithm <memcached_hash_t>` used for keys.
Each hash has its advantages and its weaknesses. If you don't know or
don't care, just go with the default.
- Support for `MEMCACHED_HASH_HSIEH` is a compile time option that is
- disabled by default. To enable tests for this hashing algorithm,
- configure and build libmemcached with the Hsieh hash enabled.
-
.. enumerator:: MEMCACHED_BEHAVIOR_DISTRIBUTION
- Using this you can enable different means of distributing values to
- servers.
+ Setting a `memcached_server_distribution_t` you can enable different
+ means of distributing values to servers.
- The default method is `MEMCACHED_DISTRIBUTION_MODULA`.
+ The default method is `MEMCACHED_DISTRIBUTION_MODULA` (hash of the
+ key modulo number of servers).
You can enable consistent hashing by setting
`MEMCACHED_DISTRIBUTION_CONSISTENT`. Consistent hashing delivers better
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
- Sets the hashing algorithm for host mapping on continuum.
-
- The value can be set to either:
-
- * `MEMCACHED_HASH_DEFAULT`,
- * `MEMCACHED_HASH_MD5`,
- * `MEMCACHED_HASH_CRC`,
- * `MEMCACHED_HASH_FNV1_64`,
- * `MEMCACHED_HASH_FNV1A_64`,
- * `MEMCACHED_HASH_FNV1_32`, and
- * `MEMCACHED_HASH_FNV1A_32`.
+ Sets the `hashing algorithm <memcached_hash_t>` for host mapping on continuum.
.. enumerator:: MEMCACHED_BEHAVIOR_KETAMA_COMPAT
`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
.. enumerator:: MEMCACHED_BEHAVIOR_KEEPALIVE_IDLE
Specify time, in seconds, to mark a connection as idle. This is only
- available as an option Linux.
+ available as an option on Linux.
.. enumerator:: MEMCACHED_BEHAVIOR_SOCKET_SEND_SIZE
server by hash. See `MEMCACHED_CALLBACK_NAMESPACE` for additional
information.
+.. c:type:: enum memcached_server_distribution_t memcached_server_distribution_t
+
+.. enum:: memcached_server_distribution_t
+
+ .. enumerator:: MEMCACHED_DISTRIBUTION_MODULA
+
+ Distribute keys by hash modulo number of servers.
+
+ .. enumerator:: MEMCACHED_DISTRIBUTION_CONSISTENT
+
+ Alias for `MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA`.
+
+ .. enumerator:: MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA
+
+ Unweighted consistent key distribution.
+
+ .. enumerator:: MEMCACHED_DISTRIBUTION_RANDOM
+
+ Distribute keys by :manpage:`rand(3)` modulo number of servers.
+
+ .. enumerator:: MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA_SPY
+
+ Unweighted consistent key distribution compatible with the SPY client.
+
+ .. enumerator:: MEMCACHED_DISTRIBUTION_CONSISTENT_WEIGHTED
+
+ Weighted consistent key distribution.
+
+ .. enumerator:: MEMCACHED_DISTRIBUTION_VIRTUAL_BUCKET
+
+ Consistent key distribution by virtual buckets.
+
+
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