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

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