X-Git-Url: https://git.m6w6.name/?a=blobdiff_plain;f=docs%2Fsource%2Flibmemcached%2Fmemcached_behavior.rst;h=99f3268cc1e5d08916b12400553614e73c9d0423;hb=c98c359a7ea03a0919a385bc88bf1387a47a41e8;hp=bd9998a3f0704b44545fe9809cc49d8e19eb0513;hpb=0a654f848e13d470fb07b044347f2e91d6941807;p=awesomized%2Flibmemcached diff --git a/docs/source/libmemcached/memcached_behavior.rst b/docs/source/libmemcached/memcached_behavior.rst index bd9998a3..99f3268c 100644 --- a/docs/source/libmemcached/memcached_behavior.rst +++ b/docs/source/libmemcached/memcached_behavior.rst @@ -3,8 +3,6 @@ Behaviors of the library Manipulate the behavior of a memcached_st structure. -.. index:: object: memcached_st - SYNOPSIS -------- @@ -13,13 +11,22 @@ SYNOPSIS .. 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 `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. -.. type:: enum memcached_behavior_t memcached_behavior_t +.. c:type:: enum memcached_behavior_t memcached_behavior_t .. enum:: memcached_behavior_t @@ -55,60 +62,39 @@ SYNOPSIS .. 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 `_. .. 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 ` 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 @@ -145,17 +131,7 @@ SYNOPSIS .. 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 ` for host mapping on continuum. .. enumerator:: MEMCACHED_BEHAVIOR_KETAMA_COMPAT @@ -195,8 +171,8 @@ SYNOPSIS .. 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 @@ -241,7 +217,7 @@ SYNOPSIS .. 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 @@ -249,15 +225,21 @@ SYNOPSIS 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 @@ -272,7 +254,7 @@ SYNOPSIS .. 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 @@ -326,6 +308,39 @@ SYNOPSIS 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 -----------