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