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

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