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         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`