git.m6w6.name Git - m6w6/libmemcached/blob - 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         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 numbers 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     .. enumerator:: MEMCACHED_BEHAVIOR_RANDOMIZE_REPLICA_READ
 234
 235         Allows randomizing the replica reads starting point. Normally the read
 236         is done from primary server and in case of miss the read is done from
 237         primary + 1, then primary + 2 all the way to 'n' replicas.
 238
 239         If this option is set on the starting point of the replica reads is
 240         randomized between the servers.  This allows distributing read load to
 241         multiple servers with the expense of more write traffic.
 242
 243     .. enumerator:: MEMCACHED_BEHAVIOR_CORK
 244
 245         .. deprecated:: ?
 246             This option has been deprecated with the behavior now built in and
 247             used appropriately on selected platforms.
 248
 249     .. enumerator:: MEMCACHED_BEHAVIOR_KEEPALIVE
 250
 251         Enable TCP_KEEPALIVE behavior.
 252
 253     .. enumerator:: MEMCACHED_BEHAVIOR_KEEPALIVE_IDLE
 254
 255         Specify time, in seconds, to mark a connection as idle. This is only
 256         available as an option on Linux.
 257
 258     .. enumerator:: MEMCACHED_BEHAVIOR_SOCKET_SEND_SIZE
 259
 260         Find the current size of SO_SNDBUF. A value of 0 means either an error
 261         occurred or no hosts were available. It is safe to assume system default
 262         if this occurs.
 263
 264         If an error occurs you can check the last cached errno to find the
 265         specific error.
 266
 267     .. enumerator:: MEMCACHED_BEHAVIOR_SOCKET_RECV_SIZE
 268
 269         Find the current size of SO_RCVBUF. A value of 0 means either an error
 270         occurred or no hosts were available. It is safe to assume system default
 271         if this occurs.
 272
 273         If an error occurs you can check the last cached errno to find the
 274         specific error.
 275
 276     .. enumerator:: MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT
 277
 278         .. deprecated:: 0.48
 279             See `MEMCACHED_BEHAVIOR_REMOVE_FAILED_SERVERS`
 280
 281         Set this value to enable the server be removed after continuous
 282         `MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT` times connection failure.
 283
 284     .. enumerator:: MEMCACHED_BEHAVIOR_AUTO_EJECT_HOSTS
 285
 286         .. deprecated:: 0.48
 287             See `MEMCACHED_BEHAVIOR_REMOVE_FAILED_SERVERS`
 288
 289         If enabled any hosts which have been flagged as disabled will be removed
 290         from the list of servers in the `memcached_st` structure. This must be
 291         used in combination with `MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT`.
 292
 293     .. enumerator:: 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.
 297
 298     .. enumerator:: MEMCACHED_BEHAVIOR_RETRY_TIMEOUT
 299
 300         When enabled a host which is problematic will only be checked for usage
 301         based on the amount of time set by this behavior. The value is in
 302         seconds.
 303
 304     .. enumerator:: MEMCACHED_BEHAVIOR_HASH_WITH_PREFIX_KEY
 305
 306         When enabled the prefix key will be added to the key when determining
 307         server by hash. See `MEMCACHED_CALLBACK_NAMESPACE` for additional
 308         information.
 309
 310 .. c:type:: enum memcached_server_distribution_t memcached_server_distribution_t
 311
 312 .. enum:: memcached_server_distribution_t
 313
 314     .. enumerator:: MEMCACHED_DISTRIBUTION_MODULA
 315
 316         Distribute keys by hash modulo number of servers.
 317
 318     .. enumerator:: MEMCACHED_DISTRIBUTION_CONSISTENT
 319
 320         Alias for `MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA`.
 321
 322     .. enumerator:: MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA
 323
 324         Unweighted consistent key distribution.
 325
 326     .. enumerator:: MEMCACHED_DISTRIBUTION_RANDOM
 327
 328         Distribute keys by :manpage:`rand(3)` modulo number of servers.
 329
 330     .. enumerator:: MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA_SPY
 331
 332         Unweighted consistent key distribution compatible with the SPY client.
 333
 334     .. enumerator:: MEMCACHED_DISTRIBUTION_CONSISTENT_WEIGHTED
 335
 336         Weighted consistent key distribution.
 337
 338     .. enumerator:: MEMCACHED_DISTRIBUTION_VIRTUAL_BUCKET
 339
 340         Consistent key distribution by virtual buckets.
 341
 342
 343 DESCRIPTION
 344 -----------
 345
 346 `libmemcached` behavior can be modified by using `memcached_behavior_set`.
 347 Default behavior is the library strives to be quick and accurate. Some behavior,
 348 while being faster, can also result in not entirely accurate behavior (for
 349 instance, `memcached_set` will always respond with `MEMCACHED_SUCCESS`).
 350
 351 `memcached_behavior_get` takes a behavior ``flag`` and returns whether or not
 352 that behavior is currently enabled in the client.
 353
 354 `memcached_behavior_set` changes the value of a particular option of the client.
 355 It takes both a ``flag`` and a ``value``. For simple on or off options you just
 356 need to pass in a value of 1. Calls to `memcached_behavior_set` will flush and
 357 reset all connections.
 358
 359 RETURN VALUE
 360 ------------
 361
 362 `memcached_behavior_get` returns either the current value of the key, or 0
 363 or 1 on simple flag behaviors (1 being enabled). `memcached_behavior_set`
 364 returns failure or success.
 365
 366 NOTES
 367 -----
 368
 369 The `data` argument of `memcached_behavior_set` was changed in version
 370 0.17 from taking a pointer to data value, to taking a uin64_t.
 371
 372 SEE ALSO
 373 --------
 374
 375 .. only:: man
 376
 377     :manpage:`memcached(1)`
 378     :manpage:`setsockopt(3)`
 379     :manpage:`libmemcached(3)`
 380     :manpage:`memcached_strerror(3)`
 381
 382 .. only:: html
 383
 384     * :manpage:`memcached(1)`
 385     * :manpage:`setsockopt(3)`
 386     * :doc:`../libmemcached`
 387     * :doc:`memcached_strerror`