Merge pull request #140 from hussainnaqvee/patch-1
[awesomized/libmemcached] / 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 Causes `libmemcached` to use asynchronous IO. This is the fastest
66 transport available for storage functions.
67
68 .. enumerator:: MEMCACHED_BEHAVIOR_SND_TIMEOUT
69
70 This sets the microsecond behavior of the socket against the SO_SNDTIMEO
71 flag.
72
73 In cases where you cannot use non-blocking IO this will allow you to
74 still have timeouts on the sending of data.
75
76 .. enumerator:: MEMCACHED_BEHAVIOR_RCV_TIMEOUT
77
78 This sets the microsecond behavior of the socket against the SO_RCVTIMEO
79 flag.
80
81 In cases where you cannot use non-blocking IO this will allow you to
82 still have timeouts on the reading of data.
83
84 .. enumerator:: MEMCACHED_BEHAVIOR_TCP_NODELAY
85
86 Disables Nagle's algorithm.
87 See `RFC 896 <https://tools.ietf.org/html/rfc896>`_.
88
89 .. enumerator:: MEMCACHED_BEHAVIOR_HASH
90
91 Set the `hash algorithm <memcached_hash_t>` used for keys.
92
93 Each hash has its advantages and its weaknesses. If you don't know or
94 don't care, just go with the default.
95
96 .. enumerator:: MEMCACHED_BEHAVIOR_DISTRIBUTION
97
98 Setting a `memcached_server_distribution_t` you can enable different
99 means of distributing values to servers.
100
101 The default method is `MEMCACHED_DISTRIBUTION_MODULA` (hash of the
102 key modulo number of servers).
103
104 You can enable consistent hashing by setting
105 `MEMCACHED_DISTRIBUTION_CONSISTENT`. Consistent hashing delivers better
106 distribution and allows servers to be added to the cluster with minimal
107 cache losses.
108
109 Currently `MEMCACHED_DISTRIBUTION_CONSISTENT` is an alias for the value
110 `MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA`.
111
112 .. enumerator:: MEMCACHED_BEHAVIOR_CACHE_LOOKUPS
113
114 .. deprecated:: 0.46(?)
115 DNS lookups are now always cached until an error occurs with the
116 server.
117
118 Memcached can cache named lookups so that DNS lookups are made only once.
119
120 .. enumerator:: MEMCACHED_BEHAVIOR_SUPPORT_CAS
121
122 Support CAS operations (this is not enabled by default at this point in
123 the server since it imposes a slight performance penalty).
124
125 .. enumerator:: MEMCACHED_BEHAVIOR_KETAMA
126
127 Sets the default distribution to
128 `MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA` and the hash to
129 `MEMCACHED_HASH_MD5`.
130
131 .. enumerator:: MEMCACHED_BEHAVIOR_KETAMA_WEIGHTED
132
133 Sets the default distribution to
134 `MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA` with the weighted tests.
135 Makes the default hashing algorithm for keys use `MEMCACHED_HASH_MD5`.
136
137 .. enumerator:: MEMCACHED_BEHAVIOR_KETAMA_HASH
138
139 Sets the `hashing algorithm <memcached_hash_t>` for host mapping on continuum.
140
141 .. enumerator:: MEMCACHED_BEHAVIOR_KETAMA_COMPAT
142
143 Sets the compatibility mode. The value can be set to either
144 `MEMCACHED_KETAMA_COMPAT_LIBMEMCACHED` (this is the default) or
145 `MEMCACHED_KETAMA_COMPAT_SPY` to be compatible with the SPY Memcached
146 client for Java.
147
148 .. enumerator:: MEMCACHED_BEHAVIOR_POLL_TIMEOUT
149
150 Modify the timeout in milliseconds value that is used by poll. The
151 default value is -1. An signed int must be passed to
152 `memcached_behavior_set` to change this value (this requires casting).
153 For `memcached_behavior_get` a 'signed int' value will be cast and
154 returned as 'unsigned long long'.
155
156 .. enumerator:: MEMCACHED_BEHAVIOR_USER_DATA
157
158 .. deprecated:: < 0.30
159
160 .. enumerator:: MEMCACHED_BEHAVIOR_BUFFER_REQUESTS
161
162 Enabling buffered IO causes commands to "buffer" instead of being sent.
163 Any action that gets data causes this buffer to be be sent to the remote
164 connection. Quiting the connection or closing down the connection will
165 also cause the buffered data to be pushed to the remote connection.
166
167 .. enumerator:: MEMCACHED_BEHAVIOR_VERIFY_KEY
168
169 Enabling this will cause `libmemcached` to test all keys to verify that
170 they are valid keys.
171
172 .. enumerator:: MEMCACHED_BEHAVIOR_SORT_HOSTS
173
174 Enabling this will cause hosts that are added to be placed in the host
175 list in sorted order. This will defeat consistent hashing.
176
177 .. enumerator:: MEMCACHED_BEHAVIOR_CONNECT_TIMEOUT
178
179 In non-blocking mode this changes the value of the timeout during socket
180 connection in milliseconds. Specifying -1 means an infinite timeā€out.
181
182 .. enumerator:: MEMCACHED_BEHAVIOR_BINARY_PROTOCOL
183
184 Enable the use of the binary protocol. Please note that you cannot
185 toggle this flag on an open connection.
186
187 .. enumerator:: MEMCACHED_BEHAVIOR_IO_MSG_WATERMARK
188
189 Set this value to tune the number of messages that may be sent before
190 `libmemcached` should start to automatically drain the input queue.
191
192 Setting this value to high, may cause `libmemcached` to deadlock (trying
193 to send data, but the send will block because the input buffer in the
194 kernel is full).
195
196 .. enumerator:: MEMCACHED_BEHAVIOR_IO_BYTES_WATERMARK
197
198 Set this value to tune the number of bytes that may be sent before
199 `libmemcached` should start to automatically drain the input queue (need
200 at least 10 IO requests sent without reading the input buffer).
201
202 Setting this value to high, may cause libmemcached to deadlock (trying
203 to send data, but the send will block because the input buffer in the
204 kernel is full).
205
206 .. enumerator:: MEMCACHED_BEHAVIOR_IO_KEY_PREFETCH
207
208 The binary protocol works a bit different than the textual protocol in
209 that a multiget is implemented as a pipe of single get-operations which
210 are sent to the server in a chunk.
211
212 If you are using large multigets from your application, you may improve
213 the latency of the gets by setting this value so you send out the first
214 chunk of requests when you hit the specified limit. It allows the
215 servers to start processing the requests to send the data back while the
216 rest of the requests are created and sent to the server.
217
218 .. enumerator:: MEMCACHED_BEHAVIOR_NOREPLY
219
220 Set this value to specify that you really don't care about the result
221 from your storage commands (set, add, replace, append, prepend).
222
223 .. enumerator:: MEMCACHED_BEHAVIOR_NUMBER_OF_REPLICAS
224
225 Specify the number of replicas `libmemcached` should store of each item
226 (on different servers).
227
228 This replication does not dedicate certain memcached servers to store
229 the replicas in, but instead it will store the replicas together with
230 all of the other objects (on the 'n' next servers specified in your
231 server list).
232
233 Requires the binary protocol and only supports (M)GET/SET/DELETE.
234
235 **NOTE**: `libmemcached` does not guarantee nor enforce any consistency.
236
237 .. enumerator:: MEMCACHED_BEHAVIOR_RANDOMIZE_REPLICA_READ
238
239 Allows randomizing the replica reads starting point. Normally the read
240 is done from primary server and in case of failure the read is done from
241 primary + 1, then primary + 2 all the way to 'n' replicas.
242
243 This allows distributing read load to multiple servers with the expense
244 of more write traffic.
245
246 **NOTE**: Only errors to communicate with a server are considered
247 failures, so `MEMCACHED_NOTFOUND` does *not* account for failure.
248
249 .. enumerator:: MEMCACHED_BEHAVIOR_CORK
250
251 .. deprecated:: ?
252 This option has been deprecated with the behavior now built in and
253 used appropriately on selected platforms.
254
255 .. enumerator:: MEMCACHED_BEHAVIOR_KEEPALIVE
256
257 Enable TCP_KEEPALIVE behavior.
258
259 .. enumerator:: MEMCACHED_BEHAVIOR_KEEPALIVE_IDLE
260
261 Specify time, in seconds, to mark a connection as idle. This is only
262 available as an option on Linux.
263
264 .. enumerator:: MEMCACHED_BEHAVIOR_SOCKET_SEND_SIZE
265
266 Find the current size of SO_SNDBUF. A value of 0 means either an error
267 occurred or no hosts were available. It is safe to assume system default
268 if this occurs.
269
270 If an error occurs you can check the last cached errno to find the
271 specific error.
272
273 .. enumerator:: MEMCACHED_BEHAVIOR_SOCKET_RECV_SIZE
274
275 Find the current size of SO_RCVBUF. A value of 0 means either an error
276 occurred or no hosts were available. It is safe to assume system default
277 if this occurs.
278
279 If an error occurs you can check the last cached errno to find the
280 specific error.
281
282 .. enumerator:: MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT
283
284 .. deprecated:: 0.48
285 See `MEMCACHED_BEHAVIOR_REMOVE_FAILED_SERVERS`
286
287 Set this value to enable the server be removed after continuous
288 `MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT` times connection failure.
289
290 .. enumerator:: MEMCACHED_BEHAVIOR_AUTO_EJECT_HOSTS
291
292 .. deprecated:: 0.48
293 See `MEMCACHED_BEHAVIOR_REMOVE_FAILED_SERVERS`
294
295 If enabled any hosts which have been flagged as disabled will be removed
296 from the list of servers in the `memcached_st` structure. This must be
297 used in combination with `MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT`.
298
299 .. enumerator:: MEMCACHED_BEHAVIOR_REMOVE_FAILED_SERVERS
300
301 If enabled any hosts which have been flagged as disabled will be removed
302 from the list of servers in the `memcached_st` structure.
303
304 .. enumerator:: MEMCACHED_BEHAVIOR_RETRY_TIMEOUT
305
306 When enabled a host which is problematic will only be checked for usage
307 based on the amount of time set by this behavior. The value is in
308 seconds.
309
310 .. enumerator:: MEMCACHED_BEHAVIOR_HASH_WITH_PREFIX_KEY
311
312 When enabled the prefix key will be added to the key when determining
313 server by hash. See `MEMCACHED_CALLBACK_NAMESPACE` for additional
314 information.
315
316 .. c:type:: enum memcached_server_distribution_t memcached_server_distribution_t
317
318 .. enum:: memcached_server_distribution_t
319
320 .. enumerator:: MEMCACHED_DISTRIBUTION_MODULA
321
322 Distribute keys by hash modulo number of servers.
323
324 .. enumerator:: MEMCACHED_DISTRIBUTION_CONSISTENT
325
326 Alias for `MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA`.
327
328 .. enumerator:: MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA
329
330 Unweighted consistent key distribution.
331
332 .. enumerator:: MEMCACHED_DISTRIBUTION_RANDOM
333
334 Distribute keys by :manpage:`rand(3)` modulo number of servers.
335
336 .. enumerator:: MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA_SPY
337
338 Unweighted consistent key distribution compatible with the SPY client.
339
340 .. enumerator:: MEMCACHED_DISTRIBUTION_CONSISTENT_WEIGHTED
341
342 Weighted consistent key distribution.
343
344 .. enumerator:: MEMCACHED_DISTRIBUTION_VIRTUAL_BUCKET
345
346 Consistent key distribution by virtual buckets.
347
348
349 DESCRIPTION
350 -----------
351
352 `libmemcached` behavior can be modified by using `memcached_behavior_set`.
353 Default behavior is the library strives to be quick and accurate. Some behavior,
354 while being faster, can also result in not entirely accurate behavior (for
355 instance, `memcached_set` will always respond with `MEMCACHED_SUCCESS`).
356
357 `memcached_behavior_get` takes a behavior ``flag`` and returns whether or not
358 that behavior is currently enabled in the client.
359
360 `memcached_behavior_set` changes the value of a particular option of the client.
361 It takes both a ``flag`` and a ``value``. For simple on or off options you just
362 need to pass in a value of 1. Calls to `memcached_behavior_set` will flush and
363 reset all connections.
364
365 RETURN VALUE
366 ------------
367
368 `memcached_behavior_get` returns either the current value of the key, or 0
369 or 1 on simple flag behaviors (1 being enabled). `memcached_behavior_set`
370 returns failure or success.
371
372 NOTES
373 -----
374
375 The `data` argument of `memcached_behavior_set` was changed in version
376 0.17 from taking a pointer to data value, to taking a uin64_t.
377
378 SEE ALSO
379 --------
380
381 .. only:: man
382
383 :manpage:`memcached(1)`
384 :manpage:`setsockopt(3)`
385 :manpage:`libmemcached(3)`
386 :manpage:`memcached_strerror(3)`
387
388 .. only:: html
389
390 * :manpage:`memcached(1)`
391 * :manpage:`setsockopt(3)`
392 * :doc:`../libmemcached`
393 * :doc:`memcached_strerror`