jenkins-promote-staging-trunk-libmemcached-16
[awesomized/libmemcached] / docs / 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 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 Enable 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 Enable 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 MEMCACHED_BEHAVIOR_SUPPORT_CAS
95
96 .. describe:: --USE-UDP
97
98 See :manpage:`memcached_behavior_set(3)` for 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)`