Updating for 1.0.2 release
[awesomized/libmemcached] / 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)`