git.m6w6.name Git - awesomized/libmemcached/blob - docs/source/libmemcached/configuration.rst

   1 libmemcached Configuration
   2 ==========================
   3
   4 SYNOPSIS
   5 --------
   6
   7 #include <libmemcached-|libmemcached_version|/memcached.h>
   8   Compile and link with -lmemcached
   9
  10 .. function:: memcached_st *memcached(const char *string, size_t string_length)
  11
  12     :param string: configuration string
  13     :param string_length: length of the configuration string without any terminating zero
  14     :returns: allocated and initialized `memcached_st` struct
  15
  16 .. function:: memcached_return_t libmemcached_check_configuration(const char *option_string, size_t length, char *error_buffer, size_t error_buffer_size)
  17
  18     :param option_string: configuration string
  19     :param length: length of the configuration string without any terminating zero
  20     :param error_buffer: buffer used to store any error message
  21     :param error_buffer_size: available size of the `error_buffer`
  22     :returns: `memcached_return_t` indicating success
  23
  24 DESCRIPTION
  25 -----------
  26
  27 `libmemcached` implements a custom language for configuring and modifying
  28 servers. By passing in an option string you can generate a `memcached_st` object
  29 that you can use in your application directly.
  30
  31 General Options:
  32 ~~~~~~~~~~~~~~~~
  33
  34 .. describe::  --SERVER=<servername>:<optional_port>/?<optional_weight>
  35
  36     Provide a servername to be used by the client.
  37
  38     Providing a weight will cause weighting to occur with all hosts with each
  39     server getting a default weight of 1.
  40
  41 .. describe:: --SOCKET=\"<filepath>/?<optional_weight>\"
  42
  43     Provide a filepath to a UNIX socket file. Providing a weight will cause
  44     weighting to occur with all hosts with each server getting a default weight
  45     of 1.
  46
  47 .. describe:: --VERIFY-KEY
  48
  49     Verify that keys that are being used fit within the design of the protocol
  50     being used.
  51
  52 .. describe:: --REMOVE_FAILED_SERVERS
  53
  54     Enable the behavior `MEMCACHED_BEHAVIOR_REMOVE_FAILED_SERVERS`.
  55
  56 .. describe:: --BINARY-PROTOCOL
  57
  58     Force all connections to use the binary protocol.
  59
  60 .. describe:: --BUFFER-REQUESTS
  61
  62     Please see `MEMCACHED_BEHAVIOR_BUFFER_REQUESTS`.
  63
  64 .. describe:: --CONFIGURE-FILE=
  65
  66     Provide a configuration file to be used to load requests. Beware that by
  67     using a configuration file `libmemcached` will reset `memcached_st` based
  68     on information only contained in the file.
  69
  70 .. describe:: --CONNECT-TIMEOUT=
  71
  72     See `memcached_behavior_set` for `MEMCACHED_BEHAVIOR_CONNECT_TIMEOUT`.
  73
  74 .. describe:: --DISTRIBUTION=
  75
  76     Set the distribution model used by the client.
  77     See `memcached_behavior_set` for more details.
  78
  79 .. describe:: --HASH=
  80
  81     Set the hashing algorithm used for placing keys on servers.
  82
  83 .. describe:: --HASH-WITH-NAMESPACE
  84
  85     When enabled the prefix key will be added to the key when determining which
  86     server to store the data in.
  87
  88 .. describe:: --NOREPLY
  89
  90     Enable "no reply" for all calls that support this. It is highly recommended
  91     that you use this option with the binary protocol only.
  92
  93 .. describe:: --NUMBER-OF-REPLICAS=
  94
  95     Set the number of servers that keys will be replicated to.
  96
  97 .. describe:: --RANDOMIZE-REPLICA-READ
  98
  99     Select randomly the server within the replication pool to read from.
 100
 101 .. describe:: --SORT-HOSTS
 102
 103     When adding new servers always calculate their distribution based on sorted
 104     naming order.
 105
 106 .. describe:: --SUPPORT-CAS
 107
 108     See `memcached_behavior_set` for `MEMCACHED_BEHAVIOR_SUPPORT_CAS`
 109
 110 .. describe:: --USE-UDP
 111
 112     See `memcached_behavior_set` for `MEMCACHED_BEHAVIOR_USE_UDP`
 113
 114 .. describe:: --NAMESPACE=
 115
 116     A namespace is a container that provides context for keys, only other
 117     requests that know the namespace can access these values. This is
 118     accomplished by prepending the namespace value to all keys.
 119
 120 Memcached Pool Options:
 121 ~~~~~~~~~~~~~~~~~~~~~~~
 122
 123 .. describe:: --POOL-MIN
 124
 125     Initial size of pool.
 126
 127 .. describe:: --POOL-MAX
 128
 129     Maximize size of the pool.
 130
 131 I/O Options:
 132 ~~~~~~~~~~~~
 133
 134 .. describe:: --TCP-NODELAY
 135
 136     See `memcached_behavior_set` for `MEMCACHED_BEHAVIOR_TCP_NODELAY`
 137
 138 .. describe:: --TCP-KEEPALIVE
 139
 140     See `memcached_behavior_set` for `MEMCACHED_BEHAVIOR_TCP_KEEPALIVE`
 141
 142 .. describe:: --RETRY-TIMEOUT=
 143
 144     See `memcached_behavior_set` for `MEMCACHED_BEHAVIOR_RETRY_TIMEOUT`
 145
 146 .. describe:: --SERVER-FAILURE-LIMIT=
 147
 148     See `memcached_behavior_set` for `MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT`
 149
 150 .. describe:: --SND-TIMEOUT=
 151
 152     See `memcached_behavior_set` for `MEMCACHED_BEHAVIOR_SND_TIMEOUT`
 153
 154 .. describe:: --SOCKET-RECV-SIZE=
 155
 156     See `memcached_behavior_set` for `MEMCACHED_BEHAVIOR_SOCKET_RECV_SIZE`
 157
 158 .. describe:: --SOCKET-SEND-SIZE=
 159
 160     See `memcached_behavior_set` for `MEMCACHED_BEHAVIOR_SOCKET_SEND_SIZE`
 161
 162 .. describe:: --POLL-TIMEOUT=
 163
 164     Set the timeout used by :manpage:`poll(3)`.
 165
 166 .. describe:: --IO-BYTES-WATERMARK=
 167
 168 .. describe:: --IO-KEY-PREFETCH=
 169
 170 .. describe:: --IO-MSG-WATERMARK=
 171
 172 .. describe:: --TCP-KEEPIDLE
 173
 174 .. describe:: --RCV-TIMEOUT=
 175
 176 Other Options:
 177 ~~~~~~~~~~~~~~
 178
 179 .. describe:: INCLUDE
 180
 181     Include a file in configuration.
 182     Unlike ``--CONFIGURE-FILE=`` this will not reset `memcached_st`.
 183
 184 .. describe:: RESET
 185
 186     Reset `memcached_st` and continue to process.
 187
 188 .. describe:: END
 189
 190     End configuration processing.
 191
 192 .. describe:: ERROR
 193
 194     End configuration processing and throw an error.
 195
 196 ENVIRONMENT
 197 -----------
 198
 199 .. envvar:: LIBMEMCACHED
 200
 201 RETURN VALUE
 202 ------------
 203
 204 `memcached` returns a pointer to the `memcached_st` that was created (or
 205 initialized).  On an allocation failure, it returns NULL.
 206
 207 EXAMPLE
 208 -------
 209
 210 .. code-block:: c
 211
 212    const char *config_string=
 213      "--SERVER=host10.example.com "
 214      "--SERVER=host11.example.com "
 215      "--SERVER=host10.example.com";
 216    memcached_st *memc= memcached(config_string, strlen(config_string));
 217    {
 218      // ...
 219    }
 220    memcached_free(memc);
 221
 222 SEE ALSO
 223 --------
 224
 225 .. only:: man
 226
 227     :manpage:`memcached(1)`
 228     :manpage:`libmemcached(3)`
 229     :manpage:`memcached_strerror(3)`
 230
 231 .. only:: html
 232
 233     * :manpage:`memcached(1)`
 234     * :doc:`../libmemcached`
 235     * :doc:`memcached_strerror`