1MEMCACHED_BEHAVIOR(3)        libmemcached-awesome        MEMCACHED_BEHAVIOR(3)
2
3
4

NAME

6       memcached_behavior - libmemcached Documentation
7
8       Manipulate the behavior of a memcached_st structure.
9

SYNOPSIS

11       #include <libmemcached/memcached.h>
12              Compile and link with -lmemcached
13
14       uint64_t memcached_behavior_get(memcached_st *ptr, memcached_behavior_t
15       flag)
16
17              Parameters
18
19ptr -- pointer to initialized memcached_st struct
20
21flag -- memcached_behavior_t to query
22
23              Returns
24                     the vaue set for flag
25
26       memcached_return_t      memcached_behavior_set(memcached_st       *ptr,
27       memcached_behavior_t flag, uint64_t data)
28
29              Parameters
30
31ptr -- pointer to initialized memcached_st struct
32
33flag -- memcached_behavior_t to set
34
35data -- the value to set for flag
36
37              Returns
38                     memcached_return_t indicating success
39
40              Changed    in    version    0.17:    The    data   argument   of
41              memcached_behavior_set() was changed from taking  a  pointer  to
42              data value, to taking a uin64_t.
43
44
45       typedef enum memcached_behavior_t memcached_behavior_t
46
47       enum memcached_behavior_t
48
49              enumerator MEMCACHED_BEHAVIOR_USE_UDP
50                     Causes  libmemcached to use the UDP transport when commu‐
51                     nicating with a memcached server. Not all I/O  operations
52                     are tested when this behavior is enabled.
53
54                     The       following      operations      will      return
55                     MEMCACHED_NOT_SUPPORTED      when      executed      with
56                     MEMCACHED_BEHAVIOR_USE_UDP enabled:
57
58memcached_version(),
59
60memcached_stat(),
61
62memcached_get(),
63
64memcached_get_by_key(),
65
66memcached_mget(),
67
68memcached_mget_by_key(),
69
70memcached_fetch(),
71
72memcached_fetch_result(),
73
74memcached_fetch_execute().
75
76                     All  other  operations  are  tested but are executed in a
77                     'fire-and-forget' mode, in which once the client has exe‐
78                     cuted  the  operation,  no attempt will be made to ensure
79                     the operation has been  received  and  acted  on  by  the
80                     server.
81
82                     libmemcached  does  not  allow  TCP and UDP servers to be
83                     shared within the same libmemcached client 'instance'. An
84                     attempt to add a TCP server when this behavior is enabled
85                     will result in a MEMCACHED_INVALID_HOST_PROTOCOL, as will
86                     attempting to add a UDP server when this behavior has not
87                     been enabled.
88
89              enumerator MEMCACHED_BEHAVIOR_NO_BLOCK
90                     This enables SO_LINGER only, so the close(2) call on  the
91                     socket  returns immediately.  I/O is always handled asyn‐
92                     chronously in recent versions of libmemcached.
93
94              enumerator MEMCACHED_BEHAVIOR_SND_TIMEOUT
95                     This sets the microsecond behavior of the socket  against
96                     the SO_SNDTIMEO flag.
97
98              enumerator MEMCACHED_BEHAVIOR_RCV_TIMEOUT
99                     This  sets the microsecond behavior of the socket against
100                     the SO_RCVTIMEO flag.
101
102              enumerator MEMCACHED_BEHAVIOR_TCP_NODELAY
103                     Disables Nagle's algorithm.  See RFC 896.
104
105              enumerator MEMCACHED_BEHAVIOR_HASH
106                     Set the hash algorithm used for keys.
107
108                     Each hash has its advantages and its weaknesses.  If  you
109                     don't know or don't care, just go with the default.
110
111              enumerator MEMCACHED_BEHAVIOR_DISTRIBUTION
112                     Setting  a memcached_server_distribution_t you can enable
113                     different means of distributing values to servers.
114
115                     The default method is MEMCACHED_DISTRIBUTION_MODULA (hash
116                     of the key modulo number of servers).
117
118                     You    can   enable   consistent   hashing   by   setting
119                     MEMCACHED_DISTRIBUTION_CONSISTENT. Consistent hashing de‐
120                     livers better distribution and allows servers to be added
121                     to the cluster with minimal cache losses.
122
123                     Currently MEMCACHED_DISTRIBUTION_CONSISTENT is  an  alias
124                     for the value MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA.
125
126              enumerator MEMCACHED_BEHAVIOR_CACHE_LOOKUPS
127                        Deprecated  since version 0.46(?): DNS lookups are now
128                        always cached until an error occurs with the server.
129
130
131                     Memcached can cache named lookups so that DNS lookups are
132                     made only once.
133
134              enumerator MEMCACHED_BEHAVIOR_SUPPORT_CAS
135                     Support CAS operations (this is not enabled by default at
136                     this point in the server since it imposes a  slight  per‐
137                     formance penalty).
138
139              enumerator MEMCACHED_BEHAVIOR_KETAMA
140                     Sets        the       default       distribution       to
141                     MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA and the hash  to
142                     MEMCACHED_HASH_MD5.
143
144              enumerator MEMCACHED_BEHAVIOR_KETAMA_WEIGHTED
145                     Sets        the       default       distribution       to
146                     MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA     with     the
147                     weighted  tests.  Makes the default hashing algorithm for
148                     keys use MEMCACHED_HASH_MD5.
149
150              enumerator MEMCACHED_BEHAVIOR_KETAMA_HASH
151                     Sets the hashing algorithm for host mapping on continuum.
152
153              enumerator MEMCACHED_BEHAVIOR_KETAMA_COMPAT
154                     Sets the compatibility mode. The value can be set to  ei‐
155                     ther  MEMCACHED_KETAMA_COMPAT_LIBMEMCACHED  (this  is the
156                     default) or MEMCACHED_KETAMA_COMPAT_SPY to be  compatible
157                     with the SPY Memcached client for Java.
158
159              enumerator MEMCACHED_BEHAVIOR_POLL_TIMEOUT
160                     Modify  the timeout in milliseconds value that is used by
161                     poll. The default value is -1.  An  signed  int  must  be
162                     passed  to  memcached_behavior_set() to change this value
163                     (this requires casting).  For memcached_behavior_get()  a
164                     'signed int' value will be cast and returned as 'unsigned
165                     long long'.
166
167              enumerator MEMCACHED_BEHAVIOR_USER_DATA
168                     Deprecated since version <: 0.30
169
170
171              enumerator MEMCACHED_BEHAVIOR_BUFFER_REQUESTS
172                     Enabling buffered IO causes commands to "buffer"  instead
173                     of  being  sent.   Any  action that gets data causes this
174                     buffer to be be sent to the  remote  connection.  Quiting
175                     the  connection  or closing down the connection will also
176                     cause the buffered data to be pushed to the  remote  con‐
177                     nection.
178
179              enumerator MEMCACHED_BEHAVIOR_VERIFY_KEY
180                     Enabling this will cause libmemcached to test all keys to
181                     verify that they are valid keys.
182
183              enumerator MEMCACHED_BEHAVIOR_SORT_HOSTS
184                     Enabling this will cause  hosts  that  are  added  to  be
185                     placed in the host list in sorted order. This will defeat
186                     consistent hashing.
187
188              enumerator MEMCACHED_BEHAVIOR_CONNECT_TIMEOUT
189                     Set the timeout during socket connection in milliseconds.
190                     Specifying -1 means an infinite time‐out.
191
192              enumerator MEMCACHED_BEHAVIOR_BINARY_PROTOCOL
193                     Enable  the  use of the binary protocol. Please note that
194                     you cannot toggle this flag on an open connection.
195
196              enumerator MEMCACHED_BEHAVIOR_IO_MSG_WATERMARK
197                     Set this value to tune the number of messages that may be
198                     sent  before  libmemcached  should start to automatically
199                     drain the input queue.
200
201                     Setting this value to high,  may  cause  libmemcached  to
202                     deadlock  (trying  to  send data, but the send will block
203                     because the input buffer in the kernel is full).
204
205              enumerator MEMCACHED_BEHAVIOR_IO_BYTES_WATERMARK
206                     Set this value to tune the number of bytes  that  may  be
207                     sent  before  libmemcached  should start to automatically
208                     drain the input queue (need at least 10 IO requests  sent
209                     without reading the input buffer).
210
211                     Setting  this  value  to  high, may cause libmemcached to
212                     deadlock (trying to send data, but the  send  will  block
213                     because the input buffer in the kernel is full).
214
215              enumerator MEMCACHED_BEHAVIOR_IO_KEY_PREFETCH
216                     The  binary  protocol works a bit different than the tex‐
217                     tual protocol in that a multiget is implemented as a pipe
218                     of  single get-operations which are sent to the server in
219                     a chunk.
220
221                     If you are using large multigets from  your  application,
222                     you  may  improve the latency of the gets by setting this
223                     value so you send out the first chunk  of  requests  when
224                     you  hit  the  specified limit.  It allows the servers to
225                     start processing the requests to send the data back while
226                     the  rest  of  the  requests  are created and sent to the
227                     server.
228
229              enumerator MEMCACHED_BEHAVIOR_NOREPLY
230                     Set this value to specify  that  you  really  don't  care
231                     about  the  result  from your storage commands (set, add,
232                     replace, append, prepend).
233
234              enumerator MEMCACHED_BEHAVIOR_NUMBER_OF_REPLICAS
235                     Specify the number of replicas libmemcached should  store
236                     of each item (on different servers).
237
238                     This  replication  does  not  dedicate  certain memcached
239                     servers to store the replicas in,  but  instead  it  will
240                     store the replicas together with all of the other objects
241                     (on the 'n' next servers specified in your server list).
242
243                     Requires  the   binary   protocol   and   only   supports
244                     (M)GET/SET/DELETE.
245
246                     NOTE:  libmemcached  does  not  guarantee nor enforce any
247                     consistency.
248
249              enumerator MEMCACHED_BEHAVIOR_RANDOMIZE_REPLICA_READ
250                     Allows randomizing the replica reads starting point. Nor‐
251                     mally the read is done from primary server and in case of
252                     failure the read is done from primary + 1, then primary +
253                     2 all the way to 'n' replicas.
254
255                     This  allows  distributing  read load to multiple servers
256                     with the expense of more write traffic.
257
258                     NOTE: Only errors to communicate with a server  are  con‐
259                     sidered  failures, so MEMCACHED_NOTFOUND does not account
260                     for failure.
261
262              enumerator MEMCACHED_BEHAVIOR_CORK
263                     Deprecated since version ?: This option has  been  depre‐
264                     cated  with  the behavior now built in and used appropri‐
265                     ately on selected platforms.
266
267
268              enumerator MEMCACHED_BEHAVIOR_KEEPALIVE
269                     Enable TCP_KEEPALIVE behavior.
270
271              enumerator MEMCACHED_BEHAVIOR_KEEPALIVE_IDLE
272                     Specify time, in seconds, to mark a connection  as  idle.
273                     This is only available as an option on Linux.
274
275              enumerator MEMCACHED_BEHAVIOR_SOCKET_SEND_SIZE
276                     Find  the  current  size of SO_SNDBUF. A value of 0 means
277                     either an error occurred or no hosts were  available.  It
278                     is safe to assume system default if this occurs.
279
280                     If an error occurs you can check the last cached errno to
281                     find the specific error.
282
283              enumerator MEMCACHED_BEHAVIOR_SOCKET_RECV_SIZE
284                     Find the current size of SO_RCVBUF. A value  of  0  means
285                     either  an  error occurred or no hosts were available. It
286                     is safe to assume system default if this occurs.
287
288                     If an error occurs you can check the last cached errno to
289                     find the specific error.
290
291              enumerator MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT
292                     Deprecated       since       version       0.48:      See
293                     MEMCACHED_BEHAVIOR_REMOVE_FAILED_SERVERS
294
295
296                     Set this value to enable the server be removed after con‐
297                     tinuous   MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT   times
298                     connection failure.
299
300              enumerator MEMCACHED_BEHAVIOR_AUTO_EJECT_HOSTS
301                     Deprecated      since       version       0.48:       See
302                     MEMCACHED_BEHAVIOR_REMOVE_FAILED_SERVERS
303
304
305                     If  enabled any hosts which have been flagged as disabled
306                     will  be  removed  from  the  list  of  servers  in   the
307                     memcached_st  structure. This must be used in combination
308                     with MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT.
309
310              enumerator MEMCACHED_BEHAVIOR_REMOVE_FAILED_SERVERS
311                     If enabled any hosts which have been flagged as  disabled
312                     will   be  removed  from  the  list  of  servers  in  the
313                     memcached_st structure.
314
315              enumerator MEMCACHED_BEHAVIOR_RETRY_TIMEOUT
316                     When enabled a host which is  problematic  will  only  be
317                     checked for usage based on the amount of time set by this
318                     behavior. The value is in seconds.
319
320              enumerator MEMCACHED_BEHAVIOR_HASH_WITH_PREFIX_KEY
321                     When enabled the prefix key will be added to the key when
322                     determining        server        by       hash.       See
323                     MEMCACHED_CALLBACK_NAMESPACE for additional information.
324
325       typedef enum memcached_server_distribution_t memcached_server_distribu‐
326       tion_t
327
328       enum memcached_server_distribution_t
329
330              enumerator MEMCACHED_DISTRIBUTION_MODULA
331                     Distribute keys by hash modulo number of servers.
332
333              enumerator MEMCACHED_DISTRIBUTION_CONSISTENT
334                     Alias for MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA.
335
336              enumerator MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA
337                     Unweighted consistent key distribution.
338
339              enumerator MEMCACHED_DISTRIBUTION_RANDOM
340                     Distribute keys by rand(3) modulo number of servers.
341
342              enumerator MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA_SPY
343                     Unweighted  consistent  key  distribution compatible with
344                     the SPY client.
345
346              enumerator MEMCACHED_DISTRIBUTION_CONSISTENT_WEIGHTED
347                     Weighted consistent key distribution.
348
349              enumerator MEMCACHED_DISTRIBUTION_VIRTUAL_BUCKET
350                     Consistent key distribution by virtual buckets.
351

DESCRIPTION

353       libmemcached     behavior     can     be     modified     by      using
354       memcached_behavior_set().   Default  behavior is the library strives to
355       be quick and accurate. Some behavior, while being faster, can also  re‐
356       sult  in  not entirely accurate behavior (for instance, memcached_set()
357       will always respond with MEMCACHED_SUCCESS).
358
359       memcached_behavior_get() takes a behavior flag and returns  whether  or
360       not that behavior is currently enabled in the client.
361
362       memcached_behavior_set()  changes  the  value of a particular option of
363       the client.  It takes both a flag and a value. For simple on or off op‐
364       tions   you   just   need   to   pass   in  a  value  of  1.  Calls  to
365       memcached_behavior_set() will flush and reset all connections.
366

RETURN VALUE

368       memcached_behavior_get() returns either the current value of  the  key,
369       or   0   or   1   on   simple   flag   behaviors   (1  being  enabled).
370       memcached_behavior_set() returns failure or success.
371

NOTES

373       The data argument of memcached_behavior_set() was  changed  in  version
374       0.17 from taking a pointer to data value, to taking a uin64_t.
375

SEE ALSO

377       memcached(1) setsockopt(3) libmemcached(3) memcached_strerror(3)
378
379
380
381
3821.1                              Jul 20, 2023            MEMCACHED_BEHAVIOR(3)
Impressum