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_NO_BLOCK
- Causes `libmemcached` to use asynchronous IO. This is the fastest
- transport available for storage functions.
+ This enables `SO_LINGER` only, so the :manpage:`close(2)` call on the
+ socket returns immediately. I/O is always handled asynchronously in
+ recent versions of `libmemcached`.
.. enumerator:: MEMCACHED_BEHAVIOR_SND_TIMEOUT
This sets the microsecond behavior of the socket against the SO_SNDTIMEO
flag.
- In cases where you cannot use non-blocking IO this will allow you to
- still have timeouts on the sending of data.
-
.. enumerator:: MEMCACHED_BEHAVIOR_RCV_TIMEOUT
This sets the microsecond behavior of the socket against the SO_RCVTIMEO
flag.
- In cases where you cannot use non-blocking IO this will allow you to
- still have timeouts on the reading of data.
-
.. 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
.. enumerator:: MEMCACHED_BEHAVIOR_CONNECT_TIMEOUT
- In non-blocking mode this changes the value of the timeout during socket
- connection in milliseconds. Specifying -1 means an infinite time‐out.
+ Set the timeout during socket connection in milliseconds.
+ Specifying -1 means an infinite time‐out.
.. enumerator:: MEMCACHED_BEHAVIOR_BINARY_PROTOCOL
`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_NUMBER_OF_REPLICAS
- Specify the numbers of replicas `libmemcached` should store of each item
+ Specify the number of replicas `libmemcached` should store of each item
(on different servers).
This replication does not dedicate certain memcached servers to store
all of the other objects (on the 'n' next servers specified in your
server list).
+ Requires the binary protocol and only supports (M)GET/SET/DELETE.
+
+ **NOTE**: `libmemcached` does not guarantee nor enforce any consistency.
+
.. enumerator:: MEMCACHED_BEHAVIOR_RANDOMIZE_REPLICA_READ
Allows randomizing the replica reads starting point. Normally the read
- is done from primary server and in case of miss the read is done from
+ is done from primary server and in case of failure the read is done from
primary + 1, then primary + 2 all the way to 'n' replicas.
- If this option is set on the starting point of the replica reads is
- randomized between the servers. This allows distributing read load to
- multiple servers with the expense of more write traffic.
+ This allows distributing read load to multiple servers with the expense
+ of more write traffic.
+
+ **NOTE**: Only errors to communicate with a server are considered
+ failures, so `MEMCACHED_NOTFOUND` does *not* account for failure.
.. 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
projects / m6w6 / libmemcached / blobdiff