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

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