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

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