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_META_PROTOCOL
184 Enable the use of the META protocol. This setting can be switched on and
185 off at will when using an ASCII protocol connection, but causes
186 a reconnect when using the binary protocol.
188 .. enumerator:: MEMCACHED_BEHAVIOR_IO_MSG_WATERMARK
190 Set this value to tune the number of messages that may be sent before
191 `libmemcached` should start to automatically drain the input queue.
193 Setting this value to high, may cause `libmemcached` to deadlock (trying
194 to send data, but the send will block because the input buffer in the
197 .. enumerator:: MEMCACHED_BEHAVIOR_IO_BYTES_WATERMARK
199 Set this value to tune the number of bytes that may be sent before
200 `libmemcached` should start to automatically drain the input queue (need
201 at least 10 IO requests sent without reading the input buffer).
203 Setting this value to high, may cause libmemcached to deadlock (trying
204 to send data, but the send will block because the input buffer in the
207 .. enumerator:: MEMCACHED_BEHAVIOR_IO_KEY_PREFETCH
209 The binary protocol works a bit different than the textual protocol in
210 that a multiget is implemented as a pipe of single get-operations which
211 are sent to the server in a chunk.
213 If you are using large multigets from your application, you may improve
214 the latency of the gets by setting this value so you send out the first
215 chunk of requests when you hit the specified limit. It allows the
216 servers to start processing the requests to send the data back while the
217 rest of the requests are created and sent to the server.
219 .. enumerator:: MEMCACHED_BEHAVIOR_NOREPLY
221 Set this value to specify that you really don't care about the result
222 from your storage commands (set, add, replace, append, prepend).
224 .. enumerator:: MEMCACHED_BEHAVIOR_NUMBER_OF_REPLICAS
226 Specify the number of replicas `libmemcached` should store of each item
227 (on different servers).
229 This replication does not dedicate certain memcached servers to store
230 the replicas in, but instead it will store the replicas together with
231 all of the other objects (on the 'n' next servers specified in your
234 Requires the binary protocol and only supports (M)GET/SET/DELETE.
236 **NOTE**: `libmemcached` does not guarantee nor enforce any consistency.
238 .. enumerator:: MEMCACHED_BEHAVIOR_RANDOMIZE_REPLICA_READ
240 Allows randomizing the replica reads starting point. Normally the read
241 is done from primary server and in case of failure the read is done from
242 primary + 1, then primary + 2 all the way to 'n' replicas.
244 This allows distributing read load to multiple servers with the expense
245 of more write traffic.
247 **NOTE**: Only errors to communicate with a server are considered
248 failures, so `MEMCACHED_NOTFOUND` does *not* account for failure.
250 .. enumerator:: MEMCACHED_BEHAVIOR_CORK
253 This option has been deprecated with the behavior now built in and
254 used appropriately on selected platforms.
256 .. enumerator:: MEMCACHED_BEHAVIOR_KEEPALIVE
258 Enable TCP_KEEPALIVE behavior.
260 .. enumerator:: MEMCACHED_BEHAVIOR_KEEPALIVE_IDLE
262 Specify time, in seconds, to mark a connection as idle. This is only
263 available as an option on Linux.
265 .. enumerator:: MEMCACHED_BEHAVIOR_SOCKET_SEND_SIZE
267 Find the current size of SO_SNDBUF. A value of 0 means either an error
268 occurred or no hosts were available. It is safe to assume system default
271 If an error occurs you can check the last cached errno to find the
274 .. enumerator:: MEMCACHED_BEHAVIOR_SOCKET_RECV_SIZE
276 Find the current size of SO_RCVBUF. A value of 0 means either an error
277 occurred or no hosts were available. It is safe to assume system default
280 If an error occurs you can check the last cached errno to find the
283 .. enumerator:: MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT
286 See `MEMCACHED_BEHAVIOR_REMOVE_FAILED_SERVERS`
288 Set this value to enable the server be removed after continuous
289 `MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT` times connection failure.
291 .. enumerator:: MEMCACHED_BEHAVIOR_AUTO_EJECT_HOSTS
294 See `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. This must be
298 used in combination with `MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT`.
300 .. enumerator:: MEMCACHED_BEHAVIOR_REMOVE_FAILED_SERVERS
302 If enabled any hosts which have been flagged as disabled will be removed
303 from the list of servers in the `memcached_st` structure.
305 .. enumerator:: MEMCACHED_BEHAVIOR_RETRY_TIMEOUT
307 When enabled a host which is problematic will only be checked for usage
308 based on the amount of time set by this behavior. The value is in
311 .. enumerator:: MEMCACHED_BEHAVIOR_HASH_WITH_PREFIX_KEY
313 When enabled the prefix key will be added to the key when determining
314 server by hash. See `MEMCACHED_CALLBACK_NAMESPACE` for additional
317 .. c:type:: enum memcached_server_distribution_t memcached_server_distribution_t
319 .. enum:: memcached_server_distribution_t
321 .. enumerator:: MEMCACHED_DISTRIBUTION_MODULA
323 Distribute keys by hash modulo number of servers.
325 .. enumerator:: MEMCACHED_DISTRIBUTION_CONSISTENT
327 Alias for `MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA`.
329 .. enumerator:: MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA
331 Unweighted consistent key distribution.
333 .. enumerator:: MEMCACHED_DISTRIBUTION_RANDOM
335 Distribute keys by :manpage:`rand(3)` modulo number of servers.
337 .. enumerator:: MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA_SPY
339 Unweighted consistent key distribution compatible with the SPY client.
341 .. enumerator:: MEMCACHED_DISTRIBUTION_CONSISTENT_WEIGHTED
343 Weighted consistent key distribution.
345 .. enumerator:: MEMCACHED_DISTRIBUTION_VIRTUAL_BUCKET
347 Consistent key distribution by virtual buckets.
353 `libmemcached` behavior can be modified by using `memcached_behavior_set`.
354 Default behavior is the library strives to be quick and accurate. Some behavior,
355 while being faster, can also result in not entirely accurate behavior (for
356 instance, `memcached_set` will always respond with `MEMCACHED_SUCCESS`).
358 `memcached_behavior_get` takes a behavior ``flag`` and returns whether or not
359 that behavior is currently enabled in the client.
361 `memcached_behavior_set` changes the value of a particular option of the client.
362 It takes both a ``flag`` and a ``value``. For simple on or off options you just
363 need to pass in a value of 1. Calls to `memcached_behavior_set` will flush and
364 reset all connections.
369 `memcached_behavior_get` returns either the current value of the key, or 0
370 or 1 on simple flag behaviors (1 being enabled). `memcached_behavior_set`
371 returns failure or success.
376 The `data` argument of `memcached_behavior_set` was changed in version
377 0.17 from taking a pointer to data value, to taking a uin64_t.
384 :manpage:`memcached(1)`
385 :manpage:`setsockopt(3)`
386 :manpage:`libmemcached(3)`
387 :manpage:`memcached_strerror(3)`
391 * :manpage:`memcached(1)`
392 * :manpage:`setsockopt(3)`
393 * :doc:`../libmemcached`
394 * :doc:`memcached_strerror`