docs: adjust non-blocking to reality
[m6w6/libmemcached] / docs / source / libmemcached / memcached_behavior.rst
1 Behaviors of the library
2 ========================
3
4 Manipulate the behavior of a memcached_st structure.
5
6 SYNOPSIS
7 --------
8
9 #include <libmemcached/memcached.h>
10 Compile and link with -lmemcached
11
12 .. function:: uint64_t memcached_behavior_get (memcached_st *ptr, memcached_behavior_t flag)
13
14 :param ptr: pointer to initialized `memcached_st` struct
15 :param flag: `memcached_behavior_t` to query
16 :returns: the vaue set for `flag`
17
18 .. function:: memcached_return_t memcached_behavior_set (memcached_st *ptr, memcached_behavior_t flag, uint64_t data)
19
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
24
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.
28
29 .. c:type:: enum memcached_behavior_t memcached_behavior_t
30
31 .. enum:: memcached_behavior_t
32
33 .. enumerator:: MEMCACHED_BEHAVIOR_USE_UDP
34
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
37 is enabled.
38
39 The following operations will return `MEMCACHED_NOT_SUPPORTED` when
40 executed with `MEMCACHED_BEHAVIOR_USE_UDP` enabled:
41
42 * `memcached_version`,
43 * `memcached_stat`,
44 * `memcached_get`,
45 * `memcached_get_by_key`,
46 * `memcached_mget`,
47 * `memcached_mget_by_key`,
48 * `memcached_fetch`,
49 * `memcached_fetch_result`,
50 * `memcached_fetch_execute`.
51
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
55 the server.
56
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.
62
63 .. enumerator:: MEMCACHED_BEHAVIOR_NO_BLOCK
64
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`.
68
69 .. enumerator:: MEMCACHED_BEHAVIOR_SND_TIMEOUT
70
71 This sets the microsecond behavior of the socket against the SO_SNDTIMEO
72 flag.
73
74 .. enumerator:: MEMCACHED_BEHAVIOR_RCV_TIMEOUT
75
76 This sets the microsecond behavior of the socket against the SO_RCVTIMEO
77 flag.
78
79 .. enumerator:: MEMCACHED_BEHAVIOR_TCP_NODELAY
80
81 Disables Nagle's algorithm.
82 See `RFC 896 <https://tools.ietf.org/html/rfc896>`_.
83
84 .. enumerator:: MEMCACHED_BEHAVIOR_HASH
85
86 Set the `hash algorithm <memcached_hash_t>` used for keys.
87
88 Each hash has its advantages and its weaknesses. If you don't know or
89 don't care, just go with the default.
90
91 .. enumerator:: MEMCACHED_BEHAVIOR_DISTRIBUTION
92
93 Setting a `memcached_server_distribution_t` you can enable different
94 means of distributing values to servers.
95
96 The default method is `MEMCACHED_DISTRIBUTION_MODULA` (hash of the
97 key modulo number of servers).
98
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
102 cache losses.
103
104 Currently `MEMCACHED_DISTRIBUTION_CONSISTENT` is an alias for the value
105 `MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA`.
106
107 .. enumerator:: MEMCACHED_BEHAVIOR_CACHE_LOOKUPS
108
109 .. deprecated:: 0.46(?)
110 DNS lookups are now always cached until an error occurs with the
111 server.
112
113 Memcached can cache named lookups so that DNS lookups are made only once.
114
115 .. enumerator:: MEMCACHED_BEHAVIOR_SUPPORT_CAS
116
117 Support CAS operations (this is not enabled by default at this point in
118 the server since it imposes a slight performance penalty).
119
120 .. enumerator:: MEMCACHED_BEHAVIOR_KETAMA
121
122 Sets the default distribution to
123 `MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA` and the hash to
124 `MEMCACHED_HASH_MD5`.
125
126 .. enumerator:: MEMCACHED_BEHAVIOR_KETAMA_WEIGHTED
127
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`.
131
132 .. enumerator:: MEMCACHED_BEHAVIOR_KETAMA_HASH
133
134 Sets the `hashing algorithm <memcached_hash_t>` for host mapping on continuum.
135
136 .. enumerator:: MEMCACHED_BEHAVIOR_KETAMA_COMPAT
137
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
141 client for Java.
142
143 .. enumerator:: MEMCACHED_BEHAVIOR_POLL_TIMEOUT
144
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'.
150
151 .. enumerator:: MEMCACHED_BEHAVIOR_USER_DATA
152
153 .. deprecated:: < 0.30
154
155 .. enumerator:: MEMCACHED_BEHAVIOR_BUFFER_REQUESTS
156
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.
161
162 .. enumerator:: MEMCACHED_BEHAVIOR_VERIFY_KEY
163
164 Enabling this will cause `libmemcached` to test all keys to verify that
165 they are valid keys.
166
167 .. enumerator:: MEMCACHED_BEHAVIOR_SORT_HOSTS
168
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.
171
172 .. enumerator:: MEMCACHED_BEHAVIOR_CONNECT_TIMEOUT
173
174 Set the timeout during socket connection in milliseconds.
175 Specifying -1 means an infinite timeā€out.
176
177 .. enumerator:: MEMCACHED_BEHAVIOR_BINARY_PROTOCOL
178
179 Enable the use of the binary protocol. Please note that you cannot
180 toggle this flag on an open connection.
181
182 .. enumerator:: MEMCACHED_BEHAVIOR_IO_MSG_WATERMARK
183
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.
186
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
189 kernel is full).
190
191 .. enumerator:: MEMCACHED_BEHAVIOR_IO_BYTES_WATERMARK
192
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).
196
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
199 kernel is full).
200
201 .. enumerator:: MEMCACHED_BEHAVIOR_IO_KEY_PREFETCH
202
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.
206
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.
212
213 .. enumerator:: MEMCACHED_BEHAVIOR_NOREPLY
214
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).
217
218 .. enumerator:: MEMCACHED_BEHAVIOR_NUMBER_OF_REPLICAS
219
220 Specify the number of replicas `libmemcached` should store of each item
221 (on different servers).
222
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
226 server list).
227
228 Requires the binary protocol and only supports (M)GET/SET/DELETE.
229
230 **NOTE**: `libmemcached` does not guarantee nor enforce any consistency.
231
232 .. enumerator:: MEMCACHED_BEHAVIOR_RANDOMIZE_REPLICA_READ
233
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.
237
238 This allows distributing read load to multiple servers with the expense
239 of more write traffic.
240
241 **NOTE**: Only errors to communicate with a server are considered
242 failures, so `MEMCACHED_NOTFOUND` does *not* account for failure.
243
244 .. enumerator:: MEMCACHED_BEHAVIOR_CORK
245
246 .. deprecated:: ?
247 This option has been deprecated with the behavior now built in and
248 used appropriately on selected platforms.
249
250 .. enumerator:: MEMCACHED_BEHAVIOR_KEEPALIVE
251
252 Enable TCP_KEEPALIVE behavior.
253
254 .. enumerator:: MEMCACHED_BEHAVIOR_KEEPALIVE_IDLE
255
256 Specify time, in seconds, to mark a connection as idle. This is only
257 available as an option on Linux.
258
259 .. enumerator:: MEMCACHED_BEHAVIOR_SOCKET_SEND_SIZE
260
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
263 if this occurs.
264
265 If an error occurs you can check the last cached errno to find the
266 specific error.
267
268 .. enumerator:: MEMCACHED_BEHAVIOR_SOCKET_RECV_SIZE
269
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
272 if this occurs.
273
274 If an error occurs you can check the last cached errno to find the
275 specific error.
276
277 .. enumerator:: MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT
278
279 .. deprecated:: 0.48
280 See `MEMCACHED_BEHAVIOR_REMOVE_FAILED_SERVERS`
281
282 Set this value to enable the server be removed after continuous
283 `MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT` times connection failure.
284
285 .. enumerator:: MEMCACHED_BEHAVIOR_AUTO_EJECT_HOSTS
286
287 .. deprecated:: 0.48
288 See `MEMCACHED_BEHAVIOR_REMOVE_FAILED_SERVERS`
289
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`.
293
294 .. enumerator:: MEMCACHED_BEHAVIOR_REMOVE_FAILED_SERVERS
295
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.
298
299 .. enumerator:: MEMCACHED_BEHAVIOR_RETRY_TIMEOUT
300
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
303 seconds.
304
305 .. enumerator:: MEMCACHED_BEHAVIOR_HASH_WITH_PREFIX_KEY
306
307 When enabled the prefix key will be added to the key when determining
308 server by hash. See `MEMCACHED_CALLBACK_NAMESPACE` for additional
309 information.
310
311 .. c:type:: enum memcached_server_distribution_t memcached_server_distribution_t
312
313 .. enum:: memcached_server_distribution_t
314
315 .. enumerator:: MEMCACHED_DISTRIBUTION_MODULA
316
317 Distribute keys by hash modulo number of servers.
318
319 .. enumerator:: MEMCACHED_DISTRIBUTION_CONSISTENT
320
321 Alias for `MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA`.
322
323 .. enumerator:: MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA
324
325 Unweighted consistent key distribution.
326
327 .. enumerator:: MEMCACHED_DISTRIBUTION_RANDOM
328
329 Distribute keys by :manpage:`rand(3)` modulo number of servers.
330
331 .. enumerator:: MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA_SPY
332
333 Unweighted consistent key distribution compatible with the SPY client.
334
335 .. enumerator:: MEMCACHED_DISTRIBUTION_CONSISTENT_WEIGHTED
336
337 Weighted consistent key distribution.
338
339 .. enumerator:: MEMCACHED_DISTRIBUTION_VIRTUAL_BUCKET
340
341 Consistent key distribution by virtual buckets.
342
343
344 DESCRIPTION
345 -----------
346
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`).
351
352 `memcached_behavior_get` takes a behavior ``flag`` and returns whether or not
353 that behavior is currently enabled in the client.
354
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.
359
360 RETURN VALUE
361 ------------
362
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.
366
367 NOTES
368 -----
369
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.
372
373 SEE ALSO
374 --------
375
376 .. only:: man
377
378 :manpage:`memcached(1)`
379 :manpage:`setsockopt(3)`
380 :manpage:`libmemcached(3)`
381 :manpage:`memcached_strerror(3)`
382
383 .. only:: html
384
385 * :manpage:`memcached(1)`
386 * :manpage:`setsockopt(3)`
387 * :doc:`../libmemcached`
388 * :doc:`memcached_strerror`