Apache Portable Runtime
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
apr_memcache.h
Go to the documentation of this file.
1 /* Licensed to the Apache Software Foundation (ASF) under one or more
2  * contributor license agreements. See the NOTICE file distributed with
3  * this work for additional information regarding copyright ownership.
4  * The ASF licenses this file to You under the Apache License, Version 2.0
5  * (the "License"); you may not use this file except in compliance with
6  * the License. You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef APR_MEMCACHE_H
18 #define APR_MEMCACHE_H
19 
20 /**
21  * @file apr_memcache.h
22  * @brief Client interface for memcached
23  * @remark To use this interface you must have a separate memcached
24  * server running. See the memcached website at http://www.danga.com/memcached/
25  * for more information.
26  */
27 
28 #include "apr.h"
29 #include "apr_pools.h"
30 #include "apr_time.h"
31 #include "apr_strings.h"
32 #include "apr_network_io.h"
33 #include "apr_ring.h"
34 #include "apr_buckets.h"
35 #include "apr_reslist.h"
36 #include "apr_hash.h"
37 
38 #ifdef __cplusplus
39 extern "C" {
40 #endif /* __cplusplus */
41 
42 /**
43  * @defgroup APR_Util_MC Memcached Client Routines
44  * @ingroup APR_Util
45  * @{
46  */
47 
48 /** Specifies the status of a memcached server */
49 typedef enum
50 {
51  APR_MC_SERVER_LIVE, /**< Server is alive and responding to requests */
52  APR_MC_SERVER_DEAD /**< Server is not responding to requests */
54 
55 /** Opaque memcache client connection object */
57 
58 /** Memcache Server Info Object */
61 {
62  const char *host; /**< Hostname of this Server */
63  apr_port_t port; /**< Port of this Server */
64  apr_memcache_server_status_t status; /**< @see apr_memcache_server_status_t */
65 #if APR_HAS_THREADS || defined(DOXYGEN)
66  apr_reslist_t *conns; /**< Resource list of actual client connections */
67 #else
68  apr_memcache_conn_t *conn;
69 #endif
70  apr_pool_t *p; /** Pool to use for private allocations */
71 #if APR_HAS_THREADS
73 #endif
74  apr_time_t btime;
75 };
76 
77 /* Custom hash callback function prototype, user for server selection.
78 * @param baton user selected baton
79 * @param data data to hash
80 * @param data_len length of data
81 */
82 typedef apr_uint32_t (*apr_memcache_hash_func)(void *baton,
83  const char *data,
84  const apr_size_t data_len);
85 
86 typedef struct apr_memcache_t apr_memcache_t;
87 
88 /* Custom Server Select callback function prototype.
89 * @param baton user selected baton
90 * @param mc memcache instance, use mc->live_servers to select a node
91 * @param hash hash of the selected key.
92 */
93 typedef apr_memcache_server_t* (*apr_memcache_server_func)(void *baton,
94  apr_memcache_t *mc,
95  const apr_uint32_t hash);
96 
97 /** Container for a set of memcached servers */
99 {
100  apr_uint32_t flags; /**< Flags, Not currently used */
101  apr_uint16_t nalloc; /**< Number of Servers Allocated */
102  apr_uint16_t ntotal; /**< Number of Servers Added */
103  apr_memcache_server_t **live_servers; /**< Array of Servers */
104  apr_pool_t *p; /** Pool to use for allocations */
105  void *hash_baton;
106  apr_memcache_hash_func hash_func;
107  void *server_baton;
108  apr_memcache_server_func server_func;
109 };
110 
111 /** Returned Data from a multiple get */
112 typedef struct
113 {
114  apr_status_t status;
115  const char* key;
116  apr_size_t len;
117  char *data;
118  apr_uint16_t flags;
120 
121 /**
122  * Creates a crc32 hash used to split keys between servers
123  * @param mc The memcache client object to use
124  * @param data Data to be hashed
125  * @param data_len Length of the data to use
126  * @return crc32 hash of data
127  * @remark The crc32 hash is not compatible with old memcached clients.
128  */
129 APU_DECLARE(apr_uint32_t) apr_memcache_hash(apr_memcache_t *mc,
130  const char *data,
131  const apr_size_t data_len);
132 
133 /**
134  * Pure CRC32 Hash. Used by some clients.
135  */
136 APU_DECLARE(apr_uint32_t) apr_memcache_hash_crc32(void *baton,
137  const char *data,
138  const apr_size_t data_len);
139 
140 /**
141  * hash compatible with the standard Perl Client.
142  */
143 APU_DECLARE(apr_uint32_t) apr_memcache_hash_default(void *baton,
144  const char *data,
145  const apr_size_t data_len);
146 
147 /**
148  * Picks a server based on a hash
149  * @param mc The memcache client object to use
150  * @param hash Hashed value of a Key
151  * @return server that controls specified hash
152  * @see apr_memcache_hash
153  */
155  const apr_uint32_t hash);
156 
157 /**
158  * server selection compatible with the standard Perl Client.
159  */
161  apr_memcache_t *mc,
162  const apr_uint32_t hash);
163 
164 /**
165  * Adds a server to a client object
166  * @param mc The memcache client object to use
167  * @param server Server to add
168  * @remark Adding servers is not thread safe, and should be done once at startup.
169  * @warning Changing servers after startup may cause keys to go to
170  * different servers.
171  */
173  apr_memcache_server_t *server);
174 
175 
176 /**
177  * Finds a Server object based on a hostname/port pair
178  * @param mc The memcache client object to use
179  * @param host Hostname of the server
180  * @param port Port of the server
181  * @return Server with matching Hostname and Port, or NULL if none was found.
182  */
184  const char *host,
185  apr_port_t port);
186 
187 /**
188  * Enables a Server for use again
189  * @param mc The memcache client object to use
190  * @param ms Server to Activate
191  */
194 
195 
196 /**
197  * Disable a Server
198  * @param mc The memcache client object to use
199  * @param ms Server to Disable
200  */
203 
204 /**
205  * Creates a new Server Object
206  * @param p Pool to use
207  * @param host hostname of the server
208  * @param port port of the server
209  * @param min minimum number of client sockets to open
210  * @param smax soft maximum number of client connections to open
211  * @param max hard maximum number of client connections
212  * @param ttl time to live in microseconds of a client connection
213  * @param ns location of the new server object
214  * @see apr_reslist_create
215  * @remark min, smax, and max are only used when APR_HAS_THREADS
216  */
218  const char *host,
219  apr_port_t port,
220  apr_uint32_t min,
221  apr_uint32_t smax,
222  apr_uint32_t max,
223  apr_uint32_t ttl,
224  apr_memcache_server_t **ns);
225 /**
226  * Creates a new memcached client object
227  * @param p Pool to use
228  * @param max_servers maximum number of servers
229  * @param flags Not currently used
230  * @param mc location of the new memcache client object
231  */
233  apr_uint16_t max_servers,
234  apr_uint32_t flags,
235  apr_memcache_t **mc);
236 
237 /**
238  * Gets a value from the server, allocating the value out of p
239  * @param mc client to use
240  * @param p Pool to use
241  * @param key null terminated string containing the key
242  * @param baton location of the allocated value
243  * @param len length of data at baton
244  * @param flags any flags set by the client for this key
245  * @return
246  */
248  apr_pool_t *p,
249  const char* key,
250  char **baton,
251  apr_size_t *len,
252  apr_uint16_t *flags);
253 
254 
255 /**
256  * Add a key to a hash for a multiget query
257  * if the hash (*value) is NULL it will be created
258  * @param data_pool pool from where the hash and their items are created from
259  * @param key null terminated string containing the key
260  * @param values hash of keys and values that this key will be added to
261  * @return
262  */
263 APU_DECLARE(void) apr_memcache_add_multget_key(apr_pool_t *data_pool,
264  const char* key,
265  apr_hash_t **values);
266 
267 /**
268  * Gets multiple values from the server, allocating the values out of p
269  * @param mc client to use
270  * @param temp_pool Pool used for temporary allocations. May be cleared inside this
271  * call.
272  * @param data_pool Pool used to allocate data for the returned values.
273  * @param values hash of apr_memcache_value_t keyed by strings, contains the
274  * result of the multiget call.
275  * @return
276  */
278  apr_pool_t *temp_pool,
279  apr_pool_t *data_pool,
280  apr_hash_t *values);
281 
282 /**
283  * Sets a value by key on the server
284  * @param mc client to use
285  * @param key null terminated string containing the key
286  * @param baton data to store on the server
287  * @param data_size length of data at baton
288  * @param timeout time in seconds for the data to live on the server
289  * @param flags any flags set by the client for this key
290  */
292  const char *key,
293  char *baton,
294  const apr_size_t data_size,
295  apr_uint32_t timeout,
296  apr_uint16_t flags);
297 
298 /**
299  * Adds value by key on the server
300  * @param mc client to use
301  * @param key null terminated string containing the key
302  * @param baton data to store on the server
303  * @param data_size length of data at baton
304  * @param timeout time for the data to live on the server
305  * @param flags any flags set by the client for this key
306  * @return APR_SUCCESS if the key was added, APR_EEXIST if the key
307  * already exists on the server.
308  */
310  const char *key,
311  char *baton,
312  const apr_size_t data_size,
313  apr_uint32_t timeout,
314  apr_uint16_t flags);
315 
316 /**
317  * Replaces value by key on the server
318  * @param mc client to use
319  * @param key null terminated string containing the key
320  * @param baton data to store on the server
321  * @param data_size length of data at baton
322  * @param timeout time for the data to live on the server
323  * @param flags any flags set by the client for this key
324  * @return APR_SUCCESS if the key was added, APR_EEXIST if the key
325  * did not exist on the server.
326  */
328  const char *key,
329  char *baton,
330  const apr_size_t data_size,
331  apr_uint32_t timeout,
332  apr_uint16_t flags);
333 /**
334  * Deletes a key from a server
335  * @param mc client to use
336  * @param key null terminated string containing the key
337  * @param timeout time for the delete to stop other clients from adding
338  */
340  const char *key,
341  apr_uint32_t timeout);
342 
343 /**
344  * Increments a value
345  * @param mc client to use
346  * @param key null terminated string containing the key
347  * @param n number to increment by
348  * @param nv new value after incrementing
349  */
351  const char *key,
352  apr_int32_t n,
353  apr_uint32_t *nv);
354 
355 /**
356  * Decrements a value
357  * @param mc client to use
358  * @param key null terminated string containing the key
359  * @param n number to decrement by
360  * @param new_value new value after decrementing
361  */
363  const char *key,
364  apr_int32_t n,
365  apr_uint32_t *new_value);
366 
367 /**
368  * Query a server's version
369  * @param ms server to query
370  * @param p Pool to allocate answer from
371  * @param baton location to store server version string
372  * @param len length of the server version string
373  */
375  apr_pool_t *p,
376  char **baton);
377 
378 typedef struct
379 {
380  /** Version string of this server */
381  const char *version;
382  /** Process id of this server process */
383  apr_uint32_t pid;
384  /** Number of seconds this server has been running */
385  apr_uint32_t uptime;
386  /** current UNIX time according to the server */
388  /** The size of a pointer on the current machine */
389  apr_uint32_t pointer_size;
390  /** Accumulated user time for this process */
392  /** Accumulated system time for this process */
394  /** Current number of items stored by the server */
395  apr_uint32_t curr_items;
396  /** Total number of items stored by this server */
397  apr_uint32_t total_items;
398  /** Current number of bytes used by this server to store items */
399  apr_uint64_t bytes;
400  /** Number of open connections */
401  apr_uint32_t curr_connections;
402  /** Total number of connections opened since the server started running */
403  apr_uint32_t total_connections;
404  /** Number of connection structures allocated by the server */
405  apr_uint32_t connection_structures;
406  /** Cumulative number of retrieval requests */
407  apr_uint32_t cmd_get;
408  /** Cumulative number of storage requests */
409  apr_uint32_t cmd_set;
410  /** Number of keys that have been requested and found present */
411  apr_uint32_t get_hits;
412  /** Number of items that have been requested and not found */
413  apr_uint32_t get_misses;
414  /** Number of items removed from cache because they passed their
415  expiration time */
416  apr_uint64_t evictions;
417  /** Total number of bytes read by this server */
418  apr_uint64_t bytes_read;
419  /** Total number of bytes sent by this server */
420  apr_uint64_t bytes_written;
421  /** Number of bytes this server is allowed to use for storage. */
422  apr_uint32_t limit_maxbytes;
423  /** Number of threads the server is running (if built with threading) */
424  apr_uint32_t threads;
426 
427 /**
428  * Query a server for statistics
429  * @param ms server to query
430  * @param p Pool to allocate answer from
431  * @param stats location of the new statistics structure
432  */
434  apr_pool_t *p,
435  apr_memcache_stats_t **stats);
436 
437 
438 /** @} */
439 
440 #ifdef __cplusplus
441 }
442 #endif
443 
444 #endif /* APR_MEMCACHE_H */