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 .. index:: object: memcached_st
   7
   8 SYNOPSIS
   9 --------
  10
  11 #include <libmemcached/memcached.h>
  12   Compile and link with -lmemcached
  13
  14 .. function:: uint64_t memcached_behavior_get (memcached_st *ptr, memcached_behavior_t flag)
  15
  16 .. function:: memcached_return_t memcached_behavior_set (memcached_st *ptr, memcached_behavior_t flag, uint64_t data)
  17
  18     .. versionchanged:: 0.17
  19         The `data` argument of `memcached_behavior_set` was changed in
  20         from taking a pointer to data value, to taking a uin64_t.
  21
  22 .. type:: enum memcached_behavior_t memcached_behavior_t
  23
  24 .. enum:: memcached_behavior_t
  25
  26     .. enumerator:: MEMCACHED_BEHAVIOR_USE_UDP
  27
  28         Causes `libmemcached` to use the UDP transport when communicating with a
  29         memcached server. Not all I/O operations are tested when this behavior
  30         is enabled.
  31
  32         The following operations will return `MEMCACHED_NOT_SUPPORTED` when
  33         executed with `MEMCACHED_BEHAVIOR_USE_UDP` enabled:
  34
  35         * `memcached_version`,
  36         * `memcached_stat`,
  37         * `memcached_get`,
  38         * `memcached_get_by_key`,
  39         * `memcached_mget`,
  40         * `memcached_mget_by_key`,
  41         * `memcached_fetch`,
  42         * `memcached_fetch_result`,
  43         * `memcached_fetch_execute`.
  44
  45         All other operations are tested but are executed in a 'fire-and-forget'
  46         mode, in which once the client has executed the operation, no attempt
  47         will be made to ensure the operation has been received and acted on by
  48         the server.
  49
  50         `libmemcached` does not allow TCP and UDP servers to be shared within
  51         the same `libmemcached` client 'instance'. An attempt to add a TCP
  52         server when this behavior is enabled will result in a
  53         `MEMCACHED_INVALID_HOST_PROTOCOL`, as will attempting to add a UDP
  54         server when this behavior has not been enabled.
  55
  56     .. enumerator:: MEMCACHED_BEHAVIOR_NO_BLOCK
  57
  58         Causes `libmemcached` to use asynchronous IO. This is the fastest
  59         transport available for storage functions.
  60
  61     .. enumerator:: MEMCACHED_BEHAVIOR_SND_TIMEOUT
  62
  63         This sets the microsecond behavior of the socket against the SO_SNDTIMEO
  64         flag.
  65
  66         In cases where you cannot use non-blocking IO this will allow you to
  67         still have timeouts on the sending of data.
  68
  69     .. enumerator:: MEMCACHED_BEHAVIOR_RCV_TIMEOUT
  70
  71         This sets the microsecond behavior of the socket against the SO_RCVTIMEO
  72         flag.
  73
  74         In cases where you cannot use non-blocking IO this will allow you to
  75         still have timeouts on the reading of data.
  76
  77     .. enumerator:: MEMCACHED_BEHAVIOR_TCP_NODELAY
  78
  79         Turns on the no-delay feature for connecting sockets (may be faster in
  80         some environments).
  81
  82     .. enumerator:: MEMCACHED_BEHAVIOR_HASH
  83
  84         Set the hash algorithm used for keys.
  85
  86         The value can be set to either:
  87
  88         * `MEMCACHED_HASH_DEFAULT`,
  89         * `MEMCACHED_HASH_MD5`,
  90         * `MEMCACHED_HASH_CRC`,
  91         * `MEMCACHED_HASH_FNV1_64`,
  92         * `MEMCACHED_HASH_FNV1A_64`,
  93         * `MEMCACHED_HASH_FNV1_32`,
  94         * `MEMCACHED_HASH_FNV1A_32`,
  95         * `MEMCACHED_HASH_JENKINS`,
  96         * `MEMCACHED_HASH_HSIEH`, and
  97         * `MEMCACHED_HASH_MURMUR`.
  98
  99         Each hash has its advantages and its weaknesses. If you don't know or
 100         don't care, just go with the default.
 101
 102         Support for `MEMCACHED_HASH_HSIEH` is a compile time option that is
 103         disabled by default. To enable tests for this hashing algorithm,
 104         configure and build libmemcached with the Hsieh hash enabled.
 105
 106     .. enumerator:: MEMCACHED_BEHAVIOR_DISTRIBUTION
 107
 108         Using this you can enable different means of distributing values to
 109         servers.
 110
 111         The default method is `MEMCACHED_DISTRIBUTION_MODULA`.
 112
 113         You can enable consistent hashing by setting
 114         `MEMCACHED_DISTRIBUTION_CONSISTENT`. Consistent hashing delivers better
 115         distribution and allows servers to be added to the cluster with minimal
 116         cache losses.
 117
 118         Currently `MEMCACHED_DISTRIBUTION_CONSISTENT` is an alias for the value
 119         `MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA`.
 120
 121     .. enumerator:: MEMCACHED_BEHAVIOR_CACHE_LOOKUPS
 122
 123         .. deprecated:: 0.46(?)
 124             DNS lookups are now always cached until an error occurs with the
 125             server.
 126
 127        Memcached can cache named lookups so that DNS lookups are made only once.
 128
 129     .. enumerator:: MEMCACHED_BEHAVIOR_SUPPORT_CAS
 130
 131         Support CAS operations (this is not enabled by default at this point in
 132         the server since it imposes a slight performance penalty).
 133
 134     .. enumerator:: MEMCACHED_BEHAVIOR_KETAMA
 135
 136         Sets the default distribution to
 137         `MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA` and the hash to
 138         `MEMCACHED_HASH_MD5`.
 139
 140     .. enumerator:: MEMCACHED_BEHAVIOR_KETAMA_WEIGHTED
 141
 142         Sets the default distribution to
 143         `MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA` with the weighted tests.
 144         Makes the default hashing algorithm for keys use `MEMCACHED_HASH_MD5`.
 145
 146     .. enumerator:: MEMCACHED_BEHAVIOR_KETAMA_HASH
 147
 148         Sets the hashing algorithm for host mapping on continuum.
 149
 150         The value can be set to either:
 151
 152         * `MEMCACHED_HASH_DEFAULT`,
 153         * `MEMCACHED_HASH_MD5`,
 154         * `MEMCACHED_HASH_CRC`,
 155         * `MEMCACHED_HASH_FNV1_64`,
 156         * `MEMCACHED_HASH_FNV1A_64`,
 157         * `MEMCACHED_HASH_FNV1_32`, and
 158         * `MEMCACHED_HASH_FNV1A_32`.
 159
 160     .. enumerator:: MEMCACHED_BEHAVIOR_KETAMA_COMPAT
 161
 162         Sets the compatibility mode. The value can be set to either
 163         `MEMCACHED_KETAMA_COMPAT_LIBMEMCACHED` (this is the default) or
 164         `MEMCACHED_KETAMA_COMPAT_SPY` to be compatible with the SPY Memcached
 165         client for Java.
 166
 167     .. enumerator:: MEMCACHED_BEHAVIOR_POLL_TIMEOUT
 168
 169         Modify the timeout in milliseconds value that is used by poll. The
 170         default value is -1. An signed int must be passed to
 171         `memcached_behavior_set` to change this value (this requires casting).
 172         For `memcached_behavior_get` a 'signed int' value will be cast and
 173         returned as 'unsigned long long'.
 174
 175     .. enumerator:: MEMCACHED_BEHAVIOR_USER_DATA
 176
 177         .. deprecated:: < 0.30
 178
 179     .. enumerator:: MEMCACHED_BEHAVIOR_BUFFER_REQUESTS
 180
 181         Enabling buffered IO causes commands to "buffer" instead of being sent.
 182         Any action that gets data causes this buffer to be be sent to the remote
 183         connection. Quiting the connection or closing down the connection will
 184         also cause the buffered data to be pushed to the remote connection.
 185
 186     .. enumerator:: MEMCACHED_BEHAVIOR_VERIFY_KEY
 187
 188         Enabling this will cause `libmemcached` to test all keys to verify that
 189         they are valid keys.
 190
 191     .. enumerator:: MEMCACHED_BEHAVIOR_SORT_HOSTS
 192
 193         Enabling this will cause hosts that are added to be placed in the host
 194         list in sorted order. This will defeat consistent hashing.
 195
 196     .. enumerator:: MEMCACHED_BEHAVIOR_CONNECT_TIMEOUT
 197
 198         In non-blocking mode this changes the value of the timeout during socket
 199         connection in milliseconds. Specifying -1 means an infinite time‐out.
 200
 201     .. enumerator:: MEMCACHED_BEHAVIOR_BINARY_PROTOCOL
 202
 203         Enable the use of the binary protocol. Please note that you cannot
 204         toggle this flag on an open connection.
 205
 206     .. enumerator:: MEMCACHED_BEHAVIOR_IO_MSG_WATERMARK
 207
 208         Set this value to tune the number of messages that may be sent before
 209         `libmemcached` should start to automatically drain the input queue.
 210
 211         Setting this value to high, may cause `libmemcached` to deadlock (trying
 212         to send data, but the send will block because the input buffer in the
 213         kernel is full).
 214
 215     .. enumerator:: MEMCACHED_BEHAVIOR_IO_BYTES_WATERMARK
 216
 217         Set this value to tune the number of bytes that may be sent before
 218         `libmemcached` should start to automatically drain the input queue (need
 219         at least 10 IO requests sent without reading the input buffer).
 220
 221         Setting this value to high, may cause libmemcached to deadlock (trying
 222         to send data, but the send will block because the input buffer in the
 223         kernel is full).
 224
 225     .. enumerator:: MEMCACHED_BEHAVIOR_IO_KEY_PREFETCH
 226
 227         The binary protocol works a bit different than the textual protocol in
 228         that a multiget is implemented as a pipe of single get-operations which
 229         are sent to the server in a chunk.
 230
 231         If you are using large multigets from your application, you may improve
 232         the latency of the gets by setting this value so you send out the first
 233         chunk of requests when you hit the specified limit.  It allows the
 234         servers to start processing the requests to send the data back while the
 235         rest of the requests are created and sent to the server.
 236
 237     .. enumerator:: MEMCACHED_BEHAVIOR_NOREPLY
 238
 239         Set this value to specify that you really don't care about the result
 240         from your storage commands (set, add, replace, append, prepend).
 241
 242     .. enumerator:: MEMCACHED_BEHAVIOR_NUMBER_OF_REPLICAS
 243
 244         Specify the numbers of replicas `libmemcached` should store of each item
 245         (on different servers).
 246
 247         This replication does not dedicate certain memcached servers to store
 248         the replicas in, but instead it will store the replicas together with
 249         all of the other objects (on the 'n' next servers specified in your
 250         server list).
 251
 252     .. enumerator:: MEMCACHED_BEHAVIOR_RANDOMIZE_REPLICA_READ
 253
 254         Allows randomizing the replica reads starting point. Normally the read
 255         is done from primary server and in case of miss the read is done from
 256         primary + 1, then primary + 2 all the way to 'n' replicas.
 257
 258         If this option is set on the starting point of the replica reads is
 259         randomized between the servers.  This allows distributing read load to
 260         multiple servers with the expense of more write traffic.
 261
 262     .. enumerator:: MEMCACHED_BEHAVIOR_CORK
 263
 264         .. deprecated:: ?
 265             This option has been deprecated with the behavior now built in and
 266             used appropriately on selected platforms.
 267
 268     .. enumerator:: MEMCACHED_BEHAVIOR_KEEPALIVE
 269
 270         Enable TCP_KEEPALIVE behavior.
 271
 272     .. enumerator:: MEMCACHED_BEHAVIOR_KEEPALIVE_IDLE
 273
 274         Specify time, in seconds, to mark a connection as idle. This is only
 275         available as an option Linux.
 276
 277     .. enumerator:: MEMCACHED_BEHAVIOR_SOCKET_SEND_SIZE
 278
 279         Find the current size of SO_SNDBUF. A value of 0 means either an error
 280         occurred or no hosts were available. It is safe to assume system default
 281         if this occurs.
 282
 283         If an error occurs you can check the last cached errno to find the
 284         specific error.
 285
 286     .. enumerator:: MEMCACHED_BEHAVIOR_SOCKET_RECV_SIZE
 287
 288         Find the current size of SO_RCVBUF. A value of 0 means either an error
 289         occurred or no hosts were available. It is safe to assume system default
 290         if this occurs.
 291
 292         If an error occurs you can check the last cached errno to find the
 293         specific error.
 294
 295     .. enumerator:: MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT
 296
 297         .. deprecated:: 0.48
 298             See `MEMCACHED_BEHAVIOR_REMOVE_FAILED_SERVERS`
 299
 300         Set this value to enable the server be removed after continuous
 301         `MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT` times connection failure.
 302
 303     .. enumerator:: MEMCACHED_BEHAVIOR_AUTO_EJECT_HOSTS
 304
 305         .. deprecated:: 0.48
 306             See `MEMCACHED_BEHAVIOR_REMOVE_FAILED_SERVERS`
 307
 308         If enabled any hosts which have been flagged as disabled will be removed
 309         from the list of servers in the `memcached_st` structure. This must be
 310         used in combination with `MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT`.
 311
 312     .. enumerator:: MEMCACHED_BEHAVIOR_REMOVE_FAILED_SERVERS
 313
 314        If enabled any hosts which have been flagged as disabled will be removed
 315        from the list of servers in the `memcached_st` structure.
 316
 317     .. enumerator:: MEMCACHED_BEHAVIOR_RETRY_TIMEOUT
 318
 319         When enabled a host which is problematic will only be checked for usage
 320         based on the amount of time set by this behavior. The value is in
 321         seconds.
 322
 323     .. enumerator:: MEMCACHED_BEHAVIOR_HASH_WITH_PREFIX_KEY
 324
 325         When enabled the prefix key will be added to the key when determining
 326         server by hash. See `MEMCACHED_CALLBACK_NAMESPACE` for additional
 327         information.
 328
 329 DESCRIPTION
 330 -----------
 331
 332 `libmemcached` behavior can be modified by using `memcached_behavior_set`.
 333 Default behavior is the library strives to be quick and accurate. Some behavior,
 334 while being faster, can also result in not entirely accurate behavior (for
 335 instance, `memcached_set` will always respond with `MEMCACHED_SUCCESS`).
 336
 337 `memcached_behavior_get` takes a behavior ``flag`` and returns whether or not
 338 that behavior is currently enabled in the client.
 339
 340 `memcached_behavior_set` changes the value of a particular option of the client.
 341 It takes both a ``flag`` and a ``value``. For simple on or off options you just
 342 need to pass in a value of 1. Calls to `memcached_behavior_set` will flush and
 343 reset all connections.
 344
 345 RETURN VALUE
 346 ------------
 347
 348 `memcached_behavior_get` returns either the current value of the key, or 0
 349 or 1 on simple flag behaviors (1 being enabled). `memcached_behavior_set`
 350 returns failure or success.
 351
 352 NOTES
 353 -----
 354
 355 The `data` argument of `memcached_behavior_set` was changed in version
 356 0.17 from taking a pointer to data value, to taking a uin64_t.
 357
 358 SEE ALSO
 359 --------
 360
 361 .. only:: man
 362
 363     :manpage:`memcached(1)`
 364     :manpage:`setsockopt(3)`
 365     :manpage:`libmemcached(3)`
 366     :manpage:`memcached_strerror(3)`
 367
 368 .. only:: html
 369
 370     * :manpage:`memcached(1)`
 371     * :manpage:`setsockopt(3)`
 372     * :doc:`../libmemcached`
 373     * :doc:`memcached_strerror`