docs: flush libmemcached progress

[awesomized/libmemcached] / docs / source / libmemcached / memcached_behavior.rst

diff --git a/docs/source/libmemcached/memcached_behavior.rst b/docs/source/libmemcached/memcached_behavior.rst
index 0730230d9c6df40a92c78a254c83792eaa0cb81a..f8353d20995b65efef6c6302bdf07317c43f1ae1 100644 (file)
--- a/docs/source/libmemcached/memcached_behavior.rst
+++ b/docs/source/libmemcached/memcached_behavior.rst
@@ -3,22 +3,27 @@ Behaviors of the library
 
 Manipulate the behavior of a memcached_st structure. 
 
 
 Manipulate the behavior of a memcached_st structure. 
 

-.. index:: object: memcached_st
-

 SYNOPSIS
 --------
 
 #include <libmemcached/memcached.h>
   Compile and link with -lmemcached
 
 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)
 
 .. 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)
 
 .. 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
     .. 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
         from taking a pointer to data value, to taking a uin64_t.
 
 .. c:type:: enum memcached_behavior_t memcached_behavior_t


@@ -34,15 +39,15 @@ SYNOPSIS
         The following operations will return `MEMCACHED_NOT_SUPPORTED` when
         executed with `MEMCACHED_BEHAVIOR_USE_UDP` enabled:
 
         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
 
         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


@@ -78,47 +83,31 @@ SYNOPSIS
 
     .. enumerator:: MEMCACHED_BEHAVIOR_TCP_NODELAY
 
 
     .. 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
 
 
     .. 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.
 
 
         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
 
     .. 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.
 
 
         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
 
 
     .. enumerator:: MEMCACHED_BEHAVIOR_CACHE_LOOKUPS
 


@@ -143,21 +132,11 @@ SYNOPSIS
 
         Sets the default distribution to
         `MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA` with the weighted tests.
 
         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
 
 
     .. 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_KETAMA_COMPAT
 


@@ -220,9 +199,9 @@ SYNOPSIS
         `libmemcached` should start to automatically drain the input queue (need
         at least 10 IO requests sent without reading the input buffer).
 
         `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_IO_KEY_PREFETCH
 


@@ -264,8 +243,8 @@ SYNOPSIS
     .. enumerator:: MEMCACHED_BEHAVIOR_CORK
 
         .. deprecated:: ?
     .. 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
 


@@ -274,7 +253,7 @@ SYNOPSIS
     .. enumerator:: MEMCACHED_BEHAVIOR_KEEPALIVE_IDLE
 
         Specify time, in seconds, to mark a connection as idle. This is only
     .. 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
 
 
     .. enumerator:: MEMCACHED_BEHAVIOR_SOCKET_SEND_SIZE
 


@@ -328,33 +307,66 @@ SYNOPSIS
         server by hash. See `MEMCACHED_CALLBACK_NAMESPACE` for additional
         information.
 
         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
 -----------
 
 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
 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.
 
 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
 ------------
 
 
 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
 -----
 
 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
 0.17 from taking a pointer to data value, to taking a uin64_t.
 
 SEE ALSO