git.m6w6.name Git - awesomized/libmemcached/blob - 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`