1 Behaviors of the library
2 ========================
4 Manipulate the behavior of a memcached_st structure.
6 .. index:: object: memcached_st
11 #include <libmemcached/memcached.h>
12 Compile and link with -lmemcached
14 .. c:type:: typedef enum memcached_behavior_t memcached_behavior_t;
16 .. function:: uint64_t memcached_behavior_get (memcached_st *ptr, memcached_behavior_t flag)
18 .. function:: memcached_return_t memcached_behavior_set (memcached_st *ptr, memcached_behavior_t flag, uint64_t data)
20 .. versionchanged:: 0.17
21 The `data` argument of :func:`memcached_behavior_set` was changed in
22 from taking a pointer to data value, to taking a uin64_t.
24 .. c:type:: enum memcached_behavior_t memcached_behavior_t
26 .. enum:: memcached_behavior_t
28 .. enumerator:: MEMCACHED_BEHAVIOR_USE_UDP
30 Causes `libmemcached` to use the UDP transport when communicating with a
31 memcached server. Not all I/O operations are tested when this behavior
34 The following operations will return `MEMCACHED_NOT_SUPPORTED` when
35 executed with `MEMCACHED_BEHAVIOR_USE_UDP` enabled:
37 * :func:`memcached_version`,
38 * :func:`memcached_stat`,
39 * :func:`memcached_get`,
40 * :func:`memcached_get_by_key`,
41 * :func:`memcached_mget`,
42 * :func:`memcached_mget_by_key`,
43 * :func:`memcached_fetch`,
44 * :func:`memcached_fetch_result`,
45 * :func:`memcached_fetch_execute`.
47 All other operations are tested but are executed in a 'fire-and-forget'
48 mode, in which once the client has executed the operation, no attempt
49 will be made to ensure the operation has been received and acted on by
52 `libmemcached` does not allow TCP and UDP servers to be shared within
53 the same `libmemcached` client 'instance'. An attempt to add a TCP
54 server when this behavior is enabled will result in a
55 `MEMCACHED_INVALID_HOST_PROTOCOL`, as will attempting to add a UDP
56 server when this behavior has not been enabled.
58 .. enumerator:: MEMCACHED_BEHAVIOR_NO_BLOCK
60 Causes `libmemcached` to use asynchronous IO. This is the fastest
61 transport available for storage functions.
63 .. enumerator:: MEMCACHED_BEHAVIOR_SND_TIMEOUT
65 This sets the microsecond behavior of the socket against the SO_SNDTIMEO
68 In cases where you cannot use non-blocking IO this will allow you to
69 still have timeouts on the sending of data.
71 .. enumerator:: MEMCACHED_BEHAVIOR_RCV_TIMEOUT
73 This sets the microsecond behavior of the socket against the SO_RCVTIMEO
76 In cases where you cannot use non-blocking IO this will allow you to
77 still have timeouts on the reading of data.
79 .. enumerator:: MEMCACHED_BEHAVIOR_TCP_NODELAY
81 Turns on the no-delay feature for connecting sockets (may be faster in
84 .. enumerator:: MEMCACHED_BEHAVIOR_HASH
86 Set the hash algorithm used for keys.
88 The value can be set to either:
90 * `MEMCACHED_HASH_DEFAULT`,
91 * `MEMCACHED_HASH_MD5`,
92 * `MEMCACHED_HASH_CRC`,
93 * `MEMCACHED_HASH_FNV1_64`,
94 * `MEMCACHED_HASH_FNV1A_64`,
95 * `MEMCACHED_HASH_FNV1_32`,
96 * `MEMCACHED_HASH_FNV1A_32`,
97 * `MEMCACHED_HASH_JENKINS`,
98 * `MEMCACHED_HASH_HSIEH`, and
99 * `MEMCACHED_HASH_MURMUR`.
101 Each hash has its advantages and its weaknesses. If you don't know or
102 don't care, just go with the default.
104 Support for `MEMCACHED_HASH_HSIEH` is a compile time option that is
105 disabled by default. To enable tests for this hashing algorithm,
106 configure and build libmemcached with the Hsieh hash enabled.
108 .. enumerator:: MEMCACHED_BEHAVIOR_DISTRIBUTION
110 Using this you can enable different means of distributing values to
113 The default method is `MEMCACHED_DISTRIBUTION_MODULA`.
115 You can enable consistent hashing by setting
116 `MEMCACHED_DISTRIBUTION_CONSISTENT`. Consistent hashing delivers better
117 distribution and allows servers to be added to the cluster with minimal
120 Currently `MEMCACHED_DISTRIBUTION_CONSISTENT` is an alias for the
121 value type:`MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA`.
123 .. enumerator:: MEMCACHED_BEHAVIOR_CACHE_LOOKUPS
125 .. deprecated:: 0.46(?)
126 DNS lookups are now always cached until an error occurs with the
129 Memcached can cache named lookups so that DNS lookups are made only once.
131 .. enumerator:: MEMCACHED_BEHAVIOR_SUPPORT_CAS
133 Support CAS operations (this is not enabled by default at this point in
134 the server since it imposes a slight performance penalty).
136 .. enumerator:: MEMCACHED_BEHAVIOR_KETAMA
138 Sets the default distribution to
139 `MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA` and the hash to
140 `MEMCACHED_HASH_MD5`.
142 .. enumerator:: MEMCACHED_BEHAVIOR_KETAMA_WEIGHTED
144 Sets the default distribution to
145 `MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA` with the weighted tests.
146 Makes the default hashing algorithm for keys use MD5.
148 .. enumerator:: MEMCACHED_BEHAVIOR_KETAMA_HASH
150 Sets the hashing algorithm for host mapping on continuum.
152 The value can be set to either:
154 * `MEMCACHED_HASH_DEFAULT`,
155 * `MEMCACHED_HASH_MD5`,
156 * `MEMCACHED_HASH_CRC`,
157 * `MEMCACHED_HASH_FNV1_64`,
158 * `MEMCACHED_HASH_FNV1A_64`,
159 * `MEMCACHED_HASH_FNV1_32`, and
160 * `MEMCACHED_HASH_FNV1A_32`.
162 .. enumerator:: MEMCACHED_BEHAVIOR_KETAMA_COMPAT
164 Sets the compatibility mode. The value can be set to either
165 `MEMCACHED_KETAMA_COMPAT_LIBMEMCACHED` (this is the default) or
166 `MEMCACHED_KETAMA_COMPAT_SPY` to be compatible with the SPY Memcached
169 .. enumerator:: MEMCACHED_BEHAVIOR_POLL_TIMEOUT
171 Modify the timeout in milliseconds value that is used by poll. The
172 default value is -1. An signed int must be passed to
173 `memcached_behavior_set` to change this value (this requires casting).
174 For `memcached_behavior_get` a 'signed int' value will be cast and
175 returned as 'unsigned long long'.
177 .. enumerator:: MEMCACHED_BEHAVIOR_USER_DATA
179 .. deprecated:: < 0.30
181 .. enumerator:: MEMCACHED_BEHAVIOR_BUFFER_REQUESTS
183 Enabling buffered IO causes commands to "buffer" instead of being sent.
184 Any action that gets data causes this buffer to be be sent to the remote
185 connection. Quiting the connection or closing down the connection will
186 also cause the buffered data to be pushed to the remote connection.
188 .. enumerator:: MEMCACHED_BEHAVIOR_VERIFY_KEY
190 Enabling this will cause `libmemcached` to test all keys to verify that
193 .. enumerator:: MEMCACHED_BEHAVIOR_SORT_HOSTS
195 Enabling this will cause hosts that are added to be placed in the host
196 list in sorted order. This will defeat consistent hashing.
198 .. enumerator:: MEMCACHED_BEHAVIOR_CONNECT_TIMEOUT
200 In non-blocking mode this changes the value of the timeout during socket
201 connection in milliseconds. Specifying -1 means an infinite timeāout.
203 .. enumerator:: MEMCACHED_BEHAVIOR_BINARY_PROTOCOL
205 Enable the use of the binary protocol. Please note that you cannot
206 toggle this flag on an open connection.
208 .. enumerator:: MEMCACHED_BEHAVIOR_IO_MSG_WATERMARK
210 Set this value to tune the number of messages that may be sent before
211 `libmemcached` should start to automatically drain the input queue.
213 Setting this value to high, may cause `libmemcached` to deadlock (trying
214 to send data, but the send will block because the input buffer in the
217 .. enumerator:: MEMCACHED_BEHAVIOR_IO_BYTES_WATERMARK
219 Set this value to tune the number of bytes that may be sent before
220 `libmemcached` should start to automatically drain the input queue (need
221 at least 10 IO requests sent without reading the input buffer).
223 Setting this value to high, may cause libmemcached to deadlock (trying to
224 send data, but the send will block because the input buffer in the kernel
227 .. enumerator:: MEMCACHED_BEHAVIOR_IO_KEY_PREFETCH
229 The binary protocol works a bit different than the textual protocol in
230 that a multiget is implemented as a pipe of single get-operations which
231 are sent to the server in a chunk.
233 If you are using large multigets from your application, you may improve
234 the latency of the gets by setting this value so you send out the first
235 chunk of requests when you hit the specified limit. It allows the
236 servers to start processing the requests to send the data back while the
237 rest of the requests are created and sent to the server.
239 .. enumerator:: MEMCACHED_BEHAVIOR_NOREPLY
241 Set this value to specify that you really don't care about the result
242 from your storage commands (set, add, replace, append, prepend).
244 .. enumerator:: MEMCACHED_BEHAVIOR_NUMBER_OF_REPLICAS
246 Specify the numbers of replicas `libmemcached` should store of each item
247 (on different servers).
249 This replication does not dedicate certain memcached servers to store
250 the replicas in, but instead it will store the replicas together with
251 all of the other objects (on the 'n' next servers specified in your
254 .. enumerator:: MEMCACHED_BEHAVIOR_RANDOMIZE_REPLICA_READ
256 Allows randomizing the replica reads starting point. Normally the read
257 is done from primary server and in case of miss the read is done from
258 primary + 1, then primary + 2 all the way to 'n' replicas.
260 If this option is set on the starting point of the replica reads is
261 randomized between the servers. This allows distributing read load to
262 multiple servers with the expense of more write traffic.
264 .. enumerator:: MEMCACHED_BEHAVIOR_CORK
267 This open has been deprecated with the behavior now built and used
268 appropriately on selected platforms.
270 .. enumerator:: MEMCACHED_BEHAVIOR_KEEPALIVE
272 Enable TCP_KEEPALIVE behavior.
274 .. enumerator:: MEMCACHED_BEHAVIOR_KEEPALIVE_IDLE
276 Specify time, in seconds, to mark a connection as idle. This is only
277 available as an option Linux.
279 .. enumerator:: MEMCACHED_BEHAVIOR_SOCKET_SEND_SIZE
281 Find the current size of SO_SNDBUF. A value of 0 means either an error
282 occurred or no hosts were available. It is safe to assume system default
285 If an error occurs you can check the last cached errno to find the
288 .. enumerator:: MEMCACHED_BEHAVIOR_SOCKET_RECV_SIZE
290 Find the current size of SO_RCVBUF. A value of 0 means either an error
291 occurred or no hosts were available. It is safe to assume system default
294 If an error occurs you can check the last cached errno to find the
297 .. enumerator:: MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT
300 See `MEMCACHED_BEHAVIOR_REMOVE_FAILED_SERVERS`
302 Set this value to enable the server be removed after continuous
303 `MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT` times connection failure.
305 .. enumerator:: MEMCACHED_BEHAVIOR_AUTO_EJECT_HOSTS
308 See `MEMCACHED_BEHAVIOR_REMOVE_FAILED_SERVERS`
310 If enabled any hosts which have been flagged as disabled will be removed
311 from the list of servers in the `memcached_st` structure. This must be
312 used in combination with `MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT`.
314 .. enumerator:: MEMCACHED_BEHAVIOR_REMOVE_FAILED_SERVERS
316 If enabled any hosts which have been flagged as disabled will be removed
317 from the list of servers in the `memcached_st` structure.
319 .. enumerator:: MEMCACHED_BEHAVIOR_RETRY_TIMEOUT
321 When enabled a host which is problematic will only be checked for usage
322 based on the amount of time set by this behavior. The value is in
325 .. enumerator:: MEMCACHED_BEHAVIOR_HASH_WITH_PREFIX_KEY
327 When enabled the prefix key will be added to the key when determining
328 server by hash. See `MEMCACHED_CALLBACK_NAMESPACE` for additional
334 `libmemcached` behavior can be modified by using :func:`memcached_behavior_set`.
335 Default behavior is the library strives to be quick and accurate. Some behavior,
336 while being faster, can also result in not entirely accurate behavior (for
337 instance, :func:`memcached_set` will always respond with `MEMCACHED_SUCCESS`).
339 :func:`memcached_behavior_get` takes a behavior flag and returns whether or not
340 that behavior is currently enabled in the client.
342 :func:`memcached_behavior_set` changes the value of a particular option of the
343 client. It takes both a flag (listed below) and a value. For simple on or off
344 options you just need to pass in a value of 1. Calls to
345 :func:`memcached_behavior_set` will flush and reset all connections.
350 :func:`memcached_behavior_get` returns either the current value of the key, or 0
351 or 1 on simple flag behaviors (1 being enabled). :func:`memcached_behavior_set`
352 returns failure or success.
357 The `data` argument of :func:`memcached_behavior_set` was changed in version
358 0.17 from taking a pointer to data value, to taking a uin64_t.
365 :manpage:`memcached(1)`
366 :manpage:`setsockopt(3)`
367 :manpage:`libmemcached(3)`
368 :manpage:`memcached_strerror(3)`
372 * :manpage:`memcached(1)`
373 * :manpage:`setsockopt(3)`
374 * :doc:`../libmemcached`
375 * :doc:`memcached_strerror`