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 .. function:: uint64_t memcached_behavior_get (memcached_st *ptr, memcached_behavior_t flag)
16 .. function:: memcached_return_t memcached_behavior_set (memcached_st *ptr, memcached_behavior_t flag, uint64_t data)
18 .. versionchanged:: 0.17
19 The `data` argument of `memcached_behavior_set` was changed in
20 from taking a pointer to data value, to taking a uin64_t.
22 .. type:: enum memcached_behavior_t memcached_behavior_t
24 .. enum:: memcached_behavior_t
26 .. enumerator:: MEMCACHED_BEHAVIOR_USE_UDP
28 Causes `libmemcached` to use the UDP transport when communicating with a
29 memcached server. Not all I/O operations are tested when this behavior
32 The following operations will return `MEMCACHED_NOT_SUPPORTED` when
33 executed with `MEMCACHED_BEHAVIOR_USE_UDP` enabled:
35 * `memcached_version`,
38 * `memcached_get_by_key`,
40 * `memcached_mget_by_key`,
42 * `memcached_fetch_result`,
43 * `memcached_fetch_execute`.
45 All other operations are tested but are executed in a 'fire-and-forget'
46 mode, in which once the client has executed the operation, no attempt
47 will be made to ensure the operation has been received and acted on by
50 `libmemcached` does not allow TCP and UDP servers to be shared within
51 the same `libmemcached` client 'instance'. An attempt to add a TCP
52 server when this behavior is enabled will result in a
53 `MEMCACHED_INVALID_HOST_PROTOCOL`, as will attempting to add a UDP
54 server when this behavior has not been enabled.
56 .. enumerator:: MEMCACHED_BEHAVIOR_NO_BLOCK
58 Causes `libmemcached` to use asynchronous IO. This is the fastest
59 transport available for storage functions.
61 .. enumerator:: MEMCACHED_BEHAVIOR_SND_TIMEOUT
63 This sets the microsecond behavior of the socket against the SO_SNDTIMEO
66 In cases where you cannot use non-blocking IO this will allow you to
67 still have timeouts on the sending of data.
69 .. enumerator:: MEMCACHED_BEHAVIOR_RCV_TIMEOUT
71 This sets the microsecond behavior of the socket against the SO_RCVTIMEO
74 In cases where you cannot use non-blocking IO this will allow you to
75 still have timeouts on the reading of data.
77 .. enumerator:: MEMCACHED_BEHAVIOR_TCP_NODELAY
79 Turns on the no-delay feature for connecting sockets (may be faster in
82 .. enumerator:: MEMCACHED_BEHAVIOR_HASH
84 Set the hash algorithm used for keys.
86 The value can be set to either:
88 * `MEMCACHED_HASH_DEFAULT`,
89 * `MEMCACHED_HASH_MD5`,
90 * `MEMCACHED_HASH_CRC`,
91 * `MEMCACHED_HASH_FNV1_64`,
92 * `MEMCACHED_HASH_FNV1A_64`,
93 * `MEMCACHED_HASH_FNV1_32`,
94 * `MEMCACHED_HASH_FNV1A_32`,
95 * `MEMCACHED_HASH_JENKINS`,
96 * `MEMCACHED_HASH_HSIEH`, and
97 * `MEMCACHED_HASH_MURMUR`.
99 Each hash has its advantages and its weaknesses. If you don't know or
100 don't care, just go with the default.
102 Support for `MEMCACHED_HASH_HSIEH` is a compile time option that is
103 disabled by default. To enable tests for this hashing algorithm,
104 configure and build libmemcached with the Hsieh hash enabled.
106 .. enumerator:: MEMCACHED_BEHAVIOR_DISTRIBUTION
108 Using this you can enable different means of distributing values to
111 The default method is `MEMCACHED_DISTRIBUTION_MODULA`.
113 You can enable consistent hashing by setting
114 `MEMCACHED_DISTRIBUTION_CONSISTENT`. Consistent hashing delivers better
115 distribution and allows servers to be added to the cluster with minimal
118 Currently `MEMCACHED_DISTRIBUTION_CONSISTENT` is an alias for the value
119 `MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA`.
121 .. enumerator:: MEMCACHED_BEHAVIOR_CACHE_LOOKUPS
123 .. deprecated:: 0.46(?)
124 DNS lookups are now always cached until an error occurs with the
127 Memcached can cache named lookups so that DNS lookups are made only once.
129 .. enumerator:: MEMCACHED_BEHAVIOR_SUPPORT_CAS
131 Support CAS operations (this is not enabled by default at this point in
132 the server since it imposes a slight performance penalty).
134 .. enumerator:: MEMCACHED_BEHAVIOR_KETAMA
136 Sets the default distribution to
137 `MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA` and the hash to
138 `MEMCACHED_HASH_MD5`.
140 .. enumerator:: MEMCACHED_BEHAVIOR_KETAMA_WEIGHTED
142 Sets the default distribution to
143 `MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA` with the weighted tests.
144 Makes the default hashing algorithm for keys use `MEMCACHED_HASH_MD5`.
146 .. enumerator:: MEMCACHED_BEHAVIOR_KETAMA_HASH
148 Sets the hashing algorithm for host mapping on continuum.
150 The value can be set to either:
152 * `MEMCACHED_HASH_DEFAULT`,
153 * `MEMCACHED_HASH_MD5`,
154 * `MEMCACHED_HASH_CRC`,
155 * `MEMCACHED_HASH_FNV1_64`,
156 * `MEMCACHED_HASH_FNV1A_64`,
157 * `MEMCACHED_HASH_FNV1_32`, and
158 * `MEMCACHED_HASH_FNV1A_32`.
160 .. enumerator:: MEMCACHED_BEHAVIOR_KETAMA_COMPAT
162 Sets the compatibility mode. The value can be set to either
163 `MEMCACHED_KETAMA_COMPAT_LIBMEMCACHED` (this is the default) or
164 `MEMCACHED_KETAMA_COMPAT_SPY` to be compatible with the SPY Memcached
167 .. enumerator:: MEMCACHED_BEHAVIOR_POLL_TIMEOUT
169 Modify the timeout in milliseconds value that is used by poll. The
170 default value is -1. An signed int must be passed to
171 `memcached_behavior_set` to change this value (this requires casting).
172 For `memcached_behavior_get` a 'signed int' value will be cast and
173 returned as 'unsigned long long'.
175 .. enumerator:: MEMCACHED_BEHAVIOR_USER_DATA
177 .. deprecated:: < 0.30
179 .. enumerator:: MEMCACHED_BEHAVIOR_BUFFER_REQUESTS
181 Enabling buffered IO causes commands to "buffer" instead of being sent.
182 Any action that gets data causes this buffer to be be sent to the remote
183 connection. Quiting the connection or closing down the connection will
184 also cause the buffered data to be pushed to the remote connection.
186 .. enumerator:: MEMCACHED_BEHAVIOR_VERIFY_KEY
188 Enabling this will cause `libmemcached` to test all keys to verify that
191 .. enumerator:: MEMCACHED_BEHAVIOR_SORT_HOSTS
193 Enabling this will cause hosts that are added to be placed in the host
194 list in sorted order. This will defeat consistent hashing.
196 .. enumerator:: MEMCACHED_BEHAVIOR_CONNECT_TIMEOUT
198 In non-blocking mode this changes the value of the timeout during socket
199 connection in milliseconds. Specifying -1 means an infinite timeāout.
201 .. enumerator:: MEMCACHED_BEHAVIOR_BINARY_PROTOCOL
203 Enable the use of the binary protocol. Please note that you cannot
204 toggle this flag on an open connection.
206 .. enumerator:: MEMCACHED_BEHAVIOR_IO_MSG_WATERMARK
208 Set this value to tune the number of messages that may be sent before
209 `libmemcached` should start to automatically drain the input queue.
211 Setting this value to high, may cause `libmemcached` to deadlock (trying
212 to send data, but the send will block because the input buffer in the
215 .. enumerator:: MEMCACHED_BEHAVIOR_IO_BYTES_WATERMARK
217 Set this value to tune the number of bytes that may be sent before
218 `libmemcached` should start to automatically drain the input queue (need
219 at least 10 IO requests sent without reading the input buffer).
221 Setting this value to high, may cause libmemcached to deadlock (trying
222 to send data, but the send will block because the input buffer in the
225 .. enumerator:: MEMCACHED_BEHAVIOR_IO_KEY_PREFETCH
227 The binary protocol works a bit different than the textual protocol in
228 that a multiget is implemented as a pipe of single get-operations which
229 are sent to the server in a chunk.
231 If you are using large multigets from your application, you may improve
232 the latency of the gets by setting this value so you send out the first
233 chunk of requests when you hit the specified limit. It allows the
234 servers to start processing the requests to send the data back while the
235 rest of the requests are created and sent to the server.
237 .. enumerator:: MEMCACHED_BEHAVIOR_NOREPLY
239 Set this value to specify that you really don't care about the result
240 from your storage commands (set, add, replace, append, prepend).
242 .. enumerator:: MEMCACHED_BEHAVIOR_NUMBER_OF_REPLICAS
244 Specify the numbers of replicas `libmemcached` should store of each item
245 (on different servers).
247 This replication does not dedicate certain memcached servers to store
248 the replicas in, but instead it will store the replicas together with
249 all of the other objects (on the 'n' next servers specified in your
252 .. enumerator:: MEMCACHED_BEHAVIOR_RANDOMIZE_REPLICA_READ
254 Allows randomizing the replica reads starting point. Normally the read
255 is done from primary server and in case of miss the read is done from
256 primary + 1, then primary + 2 all the way to 'n' replicas.
258 If this option is set on the starting point of the replica reads is
259 randomized between the servers. This allows distributing read load to
260 multiple servers with the expense of more write traffic.
262 .. enumerator:: MEMCACHED_BEHAVIOR_CORK
265 This option has been deprecated with the behavior now built in and
266 used appropriately on selected platforms.
268 .. enumerator:: MEMCACHED_BEHAVIOR_KEEPALIVE
270 Enable TCP_KEEPALIVE behavior.
272 .. enumerator:: MEMCACHED_BEHAVIOR_KEEPALIVE_IDLE
274 Specify time, in seconds, to mark a connection as idle. This is only
275 available as an option Linux.
277 .. enumerator:: MEMCACHED_BEHAVIOR_SOCKET_SEND_SIZE
279 Find the current size of SO_SNDBUF. A value of 0 means either an error
280 occurred or no hosts were available. It is safe to assume system default
283 If an error occurs you can check the last cached errno to find the
286 .. enumerator:: MEMCACHED_BEHAVIOR_SOCKET_RECV_SIZE
288 Find the current size of SO_RCVBUF. A value of 0 means either an error
289 occurred or no hosts were available. It is safe to assume system default
292 If an error occurs you can check the last cached errno to find the
295 .. enumerator:: MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT
298 See `MEMCACHED_BEHAVIOR_REMOVE_FAILED_SERVERS`
300 Set this value to enable the server be removed after continuous
301 `MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT` times connection failure.
303 .. enumerator:: MEMCACHED_BEHAVIOR_AUTO_EJECT_HOSTS
306 See `MEMCACHED_BEHAVIOR_REMOVE_FAILED_SERVERS`
308 If enabled any hosts which have been flagged as disabled will be removed
309 from the list of servers in the `memcached_st` structure. This must be
310 used in combination with `MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT`.
312 .. enumerator:: MEMCACHED_BEHAVIOR_REMOVE_FAILED_SERVERS
314 If enabled any hosts which have been flagged as disabled will be removed
315 from the list of servers in the `memcached_st` structure.
317 .. enumerator:: MEMCACHED_BEHAVIOR_RETRY_TIMEOUT
319 When enabled a host which is problematic will only be checked for usage
320 based on the amount of time set by this behavior. The value is in
323 .. enumerator:: MEMCACHED_BEHAVIOR_HASH_WITH_PREFIX_KEY
325 When enabled the prefix key will be added to the key when determining
326 server by hash. See `MEMCACHED_CALLBACK_NAMESPACE` for additional
332 `libmemcached` behavior can be modified by using `memcached_behavior_set`.
333 Default behavior is the library strives to be quick and accurate. Some behavior,
334 while being faster, can also result in not entirely accurate behavior (for
335 instance, `memcached_set` will always respond with `MEMCACHED_SUCCESS`).
337 `memcached_behavior_get` takes a behavior ``flag`` and returns whether or not
338 that behavior is currently enabled in the client.
340 `memcached_behavior_set` changes the value of a particular option of the client.
341 It takes both a ``flag`` and a ``value``. For simple on or off options you just
342 need to pass in a value of 1. Calls to `memcached_behavior_set` will flush and
343 reset all connections.
348 `memcached_behavior_get` returns either the current value of the key, or 0
349 or 1 on simple flag behaviors (1 being enabled). `memcached_behavior_set`
350 returns failure or success.
355 The `data` argument of `memcached_behavior_set` was changed in version
356 0.17 from taking a pointer to data value, to taking a uin64_t.
363 :manpage:`memcached(1)`
364 :manpage:`setsockopt(3)`
365 :manpage:`libmemcached(3)`
366 :manpage:`memcached_strerror(3)`
370 * :manpage:`memcached(1)`
371 * :manpage:`setsockopt(3)`
372 * :doc:`../libmemcached`
373 * :doc:`memcached_strerror`