1 Behaviors of the library
2 ========================
4 Manipulate the behavior of a memcached_st structure.
9 #include <libmemcached/memcached.h>
10 Compile and link with -lmemcached
12 .. function:: uint64_t memcached_behavior_get (memcached_st *ptr, memcached_behavior_t flag)
14 :param ptr: pointer to initialized `memcached_st` struct
15 :param flag: `memcached_behavior_t` to query
16 :returns: the vaue set for `flag`
18 .. function:: memcached_return_t memcached_behavior_set (memcached_st *ptr, memcached_behavior_t flag, uint64_t data)
20 :param ptr: pointer to initialized `memcached_st` struct
21 :param flag: `memcached_behavior_t` to set
22 :param data: the value to set for `flag`
23 :returns: `memcached_return_t` indicating success
25 .. versionchanged:: 0.17
26 The `data` argument of `memcached_behavior_set` was changed
27 from taking a pointer to data value, to taking a uin64_t.
29 .. c:type:: enum memcached_behavior_t memcached_behavior_t
31 .. enum:: memcached_behavior_t
33 .. enumerator:: MEMCACHED_BEHAVIOR_USE_UDP
35 Causes `libmemcached` to use the UDP transport when communicating with a
36 memcached server. Not all I/O operations are tested when this behavior
39 The following operations will return `MEMCACHED_NOT_SUPPORTED` when
40 executed with `MEMCACHED_BEHAVIOR_USE_UDP` enabled:
42 * `memcached_version`,
45 * `memcached_get_by_key`,
47 * `memcached_mget_by_key`,
49 * `memcached_fetch_result`,
50 * `memcached_fetch_execute`.
52 All other operations are tested but are executed in a 'fire-and-forget'
53 mode, in which once the client has executed the operation, no attempt
54 will be made to ensure the operation has been received and acted on by
57 `libmemcached` does not allow TCP and UDP servers to be shared within
58 the same `libmemcached` client 'instance'. An attempt to add a TCP
59 server when this behavior is enabled will result in a
60 `MEMCACHED_INVALID_HOST_PROTOCOL`, as will attempting to add a UDP
61 server when this behavior has not been enabled.
63 .. enumerator:: MEMCACHED_BEHAVIOR_NO_BLOCK
65 This enables `SO_LINGER` only, so the :manpage:`close(2)` call on the
66 socket returns immediately. I/O is always handled asynchronously in
67 recent versions of `libmemcached`.
69 .. enumerator:: MEMCACHED_BEHAVIOR_SND_TIMEOUT
71 This sets the microsecond behavior of the socket against the SO_SNDTIMEO
74 .. enumerator:: MEMCACHED_BEHAVIOR_RCV_TIMEOUT
76 This sets the microsecond behavior of the socket against the SO_RCVTIMEO
79 .. enumerator:: MEMCACHED_BEHAVIOR_TCP_NODELAY
81 Disables Nagle's algorithm.
82 See `RFC 896 <https://tools.ietf.org/html/rfc896>`_.
84 .. enumerator:: MEMCACHED_BEHAVIOR_HASH
86 Set the `hash algorithm <memcached_hash_t>` used for keys.
88 Each hash has its advantages and its weaknesses. If you don't know or
89 don't care, just go with the default.
91 .. enumerator:: MEMCACHED_BEHAVIOR_DISTRIBUTION
93 Setting a `memcached_server_distribution_t` you can enable different
94 means of distributing values to servers.
96 The default method is `MEMCACHED_DISTRIBUTION_MODULA` (hash of the
97 key modulo number of servers).
99 You can enable consistent hashing by setting
100 `MEMCACHED_DISTRIBUTION_CONSISTENT`. Consistent hashing delivers better
101 distribution and allows servers to be added to the cluster with minimal
104 Currently `MEMCACHED_DISTRIBUTION_CONSISTENT` is an alias for the value
105 `MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA`.
107 .. enumerator:: MEMCACHED_BEHAVIOR_CACHE_LOOKUPS
109 .. deprecated:: 0.46(?)
110 DNS lookups are now always cached until an error occurs with the
113 Memcached can cache named lookups so that DNS lookups are made only once.
115 .. enumerator:: MEMCACHED_BEHAVIOR_SUPPORT_CAS
117 Support CAS operations (this is not enabled by default at this point in
118 the server since it imposes a slight performance penalty).
120 .. enumerator:: MEMCACHED_BEHAVIOR_KETAMA
122 Sets the default distribution to
123 `MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA` and the hash to
124 `MEMCACHED_HASH_MD5`.
126 .. enumerator:: MEMCACHED_BEHAVIOR_KETAMA_WEIGHTED
128 Sets the default distribution to
129 `MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA` with the weighted tests.
130 Makes the default hashing algorithm for keys use `MEMCACHED_HASH_MD5`.
132 .. enumerator:: MEMCACHED_BEHAVIOR_KETAMA_HASH
134 Sets the `hashing algorithm <memcached_hash_t>` for host mapping on continuum.
136 .. enumerator:: MEMCACHED_BEHAVIOR_KETAMA_COMPAT
138 Sets the compatibility mode. The value can be set to either
139 `MEMCACHED_KETAMA_COMPAT_LIBMEMCACHED` (this is the default) or
140 `MEMCACHED_KETAMA_COMPAT_SPY` to be compatible with the SPY Memcached
143 .. enumerator:: MEMCACHED_BEHAVIOR_POLL_TIMEOUT
145 Modify the timeout in milliseconds value that is used by poll. The
146 default value is -1. An signed int must be passed to
147 `memcached_behavior_set` to change this value (this requires casting).
148 For `memcached_behavior_get` a 'signed int' value will be cast and
149 returned as 'unsigned long long'.
151 .. enumerator:: MEMCACHED_BEHAVIOR_USER_DATA
153 .. deprecated:: < 0.30
155 .. enumerator:: MEMCACHED_BEHAVIOR_BUFFER_REQUESTS
157 Enabling buffered IO causes commands to "buffer" instead of being sent.
158 Any action that gets data causes this buffer to be be sent to the remote
159 connection. Quiting the connection or closing down the connection will
160 also cause the buffered data to be pushed to the remote connection.
162 .. enumerator:: MEMCACHED_BEHAVIOR_VERIFY_KEY
164 Enabling this will cause `libmemcached` to test all keys to verify that
167 .. enumerator:: MEMCACHED_BEHAVIOR_SORT_HOSTS
169 Enabling this will cause hosts that are added to be placed in the host
170 list in sorted order. This will defeat consistent hashing.
172 .. enumerator:: MEMCACHED_BEHAVIOR_CONNECT_TIMEOUT
174 Set the timeout during socket connection in milliseconds.
175 Specifying -1 means an infinite timeāout.
177 .. enumerator:: MEMCACHED_BEHAVIOR_BINARY_PROTOCOL
179 Enable the use of the binary protocol. Please note that you cannot
180 toggle this flag on an open connection.
182 .. enumerator:: MEMCACHED_BEHAVIOR_IO_MSG_WATERMARK
184 Set this value to tune the number of messages that may be sent before
185 `libmemcached` should start to automatically drain the input queue.
187 Setting this value to high, may cause `libmemcached` to deadlock (trying
188 to send data, but the send will block because the input buffer in the
191 .. enumerator:: MEMCACHED_BEHAVIOR_IO_BYTES_WATERMARK
193 Set this value to tune the number of bytes that may be sent before
194 `libmemcached` should start to automatically drain the input queue (need
195 at least 10 IO requests sent without reading the input buffer).
197 Setting this value to high, may cause libmemcached to deadlock (trying
198 to send data, but the send will block because the input buffer in the
201 .. enumerator:: MEMCACHED_BEHAVIOR_IO_KEY_PREFETCH
203 The binary protocol works a bit different than the textual protocol in
204 that a multiget is implemented as a pipe of single get-operations which
205 are sent to the server in a chunk.
207 If you are using large multigets from your application, you may improve
208 the latency of the gets by setting this value so you send out the first
209 chunk of requests when you hit the specified limit. It allows the
210 servers to start processing the requests to send the data back while the
211 rest of the requests are created and sent to the server.
213 .. enumerator:: MEMCACHED_BEHAVIOR_NOREPLY
215 Set this value to specify that you really don't care about the result
216 from your storage commands (set, add, replace, append, prepend).
218 .. enumerator:: MEMCACHED_BEHAVIOR_NUMBER_OF_REPLICAS
220 Specify the number of replicas `libmemcached` should store of each item
221 (on different servers).
223 This replication does not dedicate certain memcached servers to store
224 the replicas in, but instead it will store the replicas together with
225 all of the other objects (on the 'n' next servers specified in your
228 Requires the binary protocol and only supports (M)GET/SET/DELETE.
230 **NOTE**: `libmemcached` does not guarantee nor enforce any consistency.
232 .. enumerator:: MEMCACHED_BEHAVIOR_RANDOMIZE_REPLICA_READ
234 Allows randomizing the replica reads starting point. Normally the read
235 is done from primary server and in case of failure the read is done from
236 primary + 1, then primary + 2 all the way to 'n' replicas.
238 This allows distributing read load to multiple servers with the expense
239 of more write traffic.
241 **NOTE**: Only errors to communicate with a server are considered
242 failures, so `MEMCACHED_NOTFOUND` does *not* account for failure.
244 .. enumerator:: MEMCACHED_BEHAVIOR_CORK
247 This option has been deprecated with the behavior now built in and
248 used appropriately on selected platforms.
250 .. enumerator:: MEMCACHED_BEHAVIOR_KEEPALIVE
252 Enable TCP_KEEPALIVE behavior.
254 .. enumerator:: MEMCACHED_BEHAVIOR_KEEPALIVE_IDLE
256 Specify time, in seconds, to mark a connection as idle. This is only
257 available as an option on Linux.
259 .. enumerator:: MEMCACHED_BEHAVIOR_SOCKET_SEND_SIZE
261 Find the current size of SO_SNDBUF. A value of 0 means either an error
262 occurred or no hosts were available. It is safe to assume system default
265 If an error occurs you can check the last cached errno to find the
268 .. enumerator:: MEMCACHED_BEHAVIOR_SOCKET_RECV_SIZE
270 Find the current size of SO_RCVBUF. A value of 0 means either an error
271 occurred or no hosts were available. It is safe to assume system default
274 If an error occurs you can check the last cached errno to find the
277 .. enumerator:: MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT
280 See `MEMCACHED_BEHAVIOR_REMOVE_FAILED_SERVERS`
282 Set this value to enable the server be removed after continuous
283 `MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT` times connection failure.
285 .. enumerator:: MEMCACHED_BEHAVIOR_AUTO_EJECT_HOSTS
288 See `MEMCACHED_BEHAVIOR_REMOVE_FAILED_SERVERS`
290 If enabled any hosts which have been flagged as disabled will be removed
291 from the list of servers in the `memcached_st` structure. This must be
292 used in combination with `MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT`.
294 .. enumerator:: MEMCACHED_BEHAVIOR_REMOVE_FAILED_SERVERS
296 If enabled any hosts which have been flagged as disabled will be removed
297 from the list of servers in the `memcached_st` structure.
299 .. enumerator:: MEMCACHED_BEHAVIOR_RETRY_TIMEOUT
301 When enabled a host which is problematic will only be checked for usage
302 based on the amount of time set by this behavior. The value is in
305 .. enumerator:: MEMCACHED_BEHAVIOR_HASH_WITH_PREFIX_KEY
307 When enabled the prefix key will be added to the key when determining
308 server by hash. See `MEMCACHED_CALLBACK_NAMESPACE` for additional
311 .. c:type:: enum memcached_server_distribution_t memcached_server_distribution_t
313 .. enum:: memcached_server_distribution_t
315 .. enumerator:: MEMCACHED_DISTRIBUTION_MODULA
317 Distribute keys by hash modulo number of servers.
319 .. enumerator:: MEMCACHED_DISTRIBUTION_CONSISTENT
321 Alias for `MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA`.
323 .. enumerator:: MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA
325 Unweighted consistent key distribution.
327 .. enumerator:: MEMCACHED_DISTRIBUTION_RANDOM
329 Distribute keys by :manpage:`rand(3)` modulo number of servers.
331 .. enumerator:: MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA_SPY
333 Unweighted consistent key distribution compatible with the SPY client.
335 .. enumerator:: MEMCACHED_DISTRIBUTION_CONSISTENT_WEIGHTED
337 Weighted consistent key distribution.
339 .. enumerator:: MEMCACHED_DISTRIBUTION_VIRTUAL_BUCKET
341 Consistent key distribution by virtual buckets.
347 `libmemcached` behavior can be modified by using `memcached_behavior_set`.
348 Default behavior is the library strives to be quick and accurate. Some behavior,
349 while being faster, can also result in not entirely accurate behavior (for
350 instance, `memcached_set` will always respond with `MEMCACHED_SUCCESS`).
352 `memcached_behavior_get` takes a behavior ``flag`` and returns whether or not
353 that behavior is currently enabled in the client.
355 `memcached_behavior_set` changes the value of a particular option of the client.
356 It takes both a ``flag`` and a ``value``. For simple on or off options you just
357 need to pass in a value of 1. Calls to `memcached_behavior_set` will flush and
358 reset all connections.
363 `memcached_behavior_get` returns either the current value of the key, or 0
364 or 1 on simple flag behaviors (1 being enabled). `memcached_behavior_set`
365 returns failure or success.
370 The `data` argument of `memcached_behavior_set` was changed in version
371 0.17 from taking a pointer to data value, to taking a uin64_t.
378 :manpage:`memcached(1)`
379 :manpage:`setsockopt(3)`
380 :manpage:`libmemcached(3)`
381 :manpage:`memcached_strerror(3)`
385 * :manpage:`memcached(1)`
386 * :manpage:`setsockopt(3)`
387 * :doc:`../libmemcached`
388 * :doc:`memcached_strerror`