Apache Portable Runtime
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_buckets.h"
34 #include "apr_ring.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
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 #if APR_HAS_THREADS
76  /** Resource list parameters */
77  int min;
78  int smax;
79  int max;
81 #endif
82 };
83 
84 /* Custom hash callback function prototype, user for server selection.
85 * @param baton user selected baton
86 * @param data data to hash
87 * @param data_len length of data
88 */
89 typedef apr_uint32_t (*apr_memcache_hash_func)(void *baton,
90  const char *data,
91  const apr_size_t data_len);
92 
93 typedef struct apr_memcache_t apr_memcache_t;
94 
95 /* Custom Server Select callback function prototype.
96 * @param baton user selected baton
97 * @param mc memcache instance, use mc->live_servers to select a node
98 * @param hash hash of the selected key.
99 */
100 typedef apr_memcache_server_t* (*apr_memcache_server_func)(void *baton,
101  apr_memcache_t *mc,
102  const apr_uint32_t hash);
103 
104 /** Container for a set of memcached servers */
106 {
107  apr_uint32_t flags; /**< Flags, Not currently used */
108  apr_uint16_t nalloc; /**< Number of Servers Allocated */
109  apr_uint16_t ntotal; /**< Number of Servers Added */
110  apr_memcache_server_t **live_servers; /**< Array of Servers */
111  apr_pool_t *p; /** Pool to use for allocations */
112  void *hash_baton;
113  apr_memcache_hash_func hash_func;
114  void *server_baton;
115  apr_memcache_server_func server_func;
116  /** Period of time before retrying a dead server */
118 };
119 
120 /** Returned Data from a multiple get */
121 typedef struct
122 {
123  apr_status_t status;
124  const char* key;
125  apr_size_t len;
126  char *data;
127  apr_uint16_t flags;
129 
130 /**
131  * Creates a crc32 hash used to split keys between servers
132  * @param mc The memcache client object to use
133  * @param data Data to be hashed
134  * @param data_len Length of the data to use
135  * @return crc32 hash of data
136  * @remark The crc32 hash is not compatible with old memcached clients.
137  */
139  const char *data,
140  const apr_size_t data_len);
141 
142 /**
143  * Pure CRC32 Hash. Used by some clients.
144  */
145 APR_DECLARE(apr_uint32_t) apr_memcache_hash_crc32(void *baton,
146  const char *data,
147  const apr_size_t data_len);
148 
149 /**
150  * hash compatible with the standard Perl Client.
151  */
152 APR_DECLARE(apr_uint32_t) apr_memcache_hash_default(void *baton,
153  const char *data,
154  const apr_size_t data_len);
155 
156 /**
157  * Picks a server based on a hash
158  * @param mc The memcache client object to use
159  * @param hash Hashed value of a Key
160  * @return server that controls specified hash
161  * @see apr_memcache_hash
162  */
164  const apr_uint32_t hash);
165 
166 /**
167  * server selection compatible with the standard Perl Client.
168  */
171  apr_memcache_t *mc,
172  const apr_uint32_t hash);
173 
174 /**
175  * Adds a server to a client object
176  * @param mc The memcache client object to use
177  * @param server Server to add
178  * @remark Adding servers is not thread safe, and should be done once at startup.
179  * @warning Changing servers after startup may cause keys to go to
180  * different servers.
181  */
183  apr_memcache_server_t *server);
184 
185 
186 /**
187  * Finds a Server object based on a hostname/port pair
188  * @param mc The memcache client object to use
189  * @param host Hostname of the server
190  * @param port Port of the server
191  * @return Server with matching Hostname and Port, or NULL if none was found.
192  */
194  const char *host,
195  apr_port_t port);
196 
197 /**
198  * Enables a Server for use again
199  * @param mc The memcache client object to use
200  * @param ms Server to Activate
201  */
204 
205 
206 /**
207  * Disable a Server
208  * @param mc The memcache client object to use
209  * @param ms Server to Disable
210  */
213 
214 
215 /**
216  * Set the retry period for retrying a dead server
217  * @param mc The memcache client object to use
218  * @param retry_period Period that must have passed until a server that was
219  * declared dead is retried.
220  */
222  apr_time_t retry_period);
223 
224 
225 /**
226  * Get the retry period for retrying a dead server
227  * @param mc The memcache client object to use
228  * @return retry_period Period that must have passed until a server that was
229  * declared dead is retried.
230  */
232 
233 
234 /**
235  * Creates a new Server Object
236  * @param p Pool to use
237  * @param host hostname of the server
238  * @param port port of the server
239  * @param min minimum number of client sockets to open
240  * @param smax soft maximum number of client connections to open
241  * @param max hard maximum number of client connections
242  * @param ttl time to live in microseconds of a client connection
243  * @param ns location of the new server object
244  * @see apr_reslist_create
245  * @remark min, smax, and max are only used when APR_HAS_THREADS
246  */
248  const char *host,
249  apr_port_t port,
250  int min,
251  int smax,
252  int max,
254  apr_memcache_server_t **ns);
255 /**
256  * Creates a new memcached client object
257  * @param p Pool to use
258  * @param max_servers maximum number of servers
259  * @param flags Not currently used
260  * @param mc location of the new memcache client object
261  */
263  apr_uint16_t max_servers,
264  apr_uint32_t flags,
265  apr_memcache_t **mc);
266 
267 /**
268  * Gets a value from the server, allocating the value out of p
269  * @param mc client to use
270  * @param p Pool to use
271  * @param key null terminated string containing the key
272  * @param baton location of the allocated value
273  * @param len length of data at baton
274  * @param flags any flags set by the client for this key
275  * @return
276  */
278  apr_pool_t *p,
279  const char* key,
280  char **baton,
281  apr_size_t *len,
282  apr_uint16_t *flags);
283 
284 
285 /**
286  * Add a key to a hash for a multiget query
287  * if the hash (*value) is NULL it will be created
288  * @param data_pool pool from where the hash and their items are created from
289  * @param key null terminated string containing the key
290  * @param values hash of keys and values that this key will be added to
291  * @return
292  */
294  const char* key,
295  apr_hash_t **values);
296 
297 /**
298  * Gets multiple values from the server, allocating the values out of p
299  * @param mc client to use
300  * @param temp_pool Pool used for temporary allocations. May be cleared inside this
301  * call.
302  * @param data_pool Pool used to allocate data for the returned values.
303  * @param values hash of apr_memcache_value_t keyed by strings, contains the
304  * result of the multiget call.
305  * @return
306  */
308  apr_pool_t *temp_pool,
309  apr_pool_t *data_pool,
310  apr_hash_t *values);
311 
312 /**
313  * Sets a value by key on the server
314  * @param mc client to use
315  * @param key null terminated string containing the key
316  * @param baton data to store on the server
317  * @param data_size length of data at baton
318  * @param timeout time in seconds for the data to live on the server
319  * @param flags any flags set by the client for this key
320  */
322  const char *key,
323  char *baton,
324  const apr_size_t data_size,
325  apr_uint32_t timeout,
326  apr_uint16_t flags);
327 
328 /**
329  * Adds value by key on the server
330  * @param mc client to use
331  * @param key null terminated string containing the key
332  * @param baton data to store on the server
333  * @param data_size length of data at baton
334  * @param timeout time for the data to live on the server
335  * @param flags any flags set by the client for this key
336  * @return APR_SUCCESS if the key was added, APR_EEXIST if the key
337  * already exists on the server.
338  */
340  const char *key,
341  char *baton,
342  const apr_size_t data_size,
343  apr_uint32_t timeout,
344  apr_uint16_t flags);
345 
346 /**
347  * Replaces value by key on the server
348  * @param mc client to use
349  * @param key null terminated string containing the key
350  * @param baton data to store on the server
351  * @param data_size length of data at baton
352  * @param timeout time for the data to live on the server
353  * @param flags any flags set by the client for this key
354  * @return APR_SUCCESS if the key was added, APR_EEXIST if the key
355  * did not exist on the server.
356  */
358  const char *key,
359  char *baton,
360  const apr_size_t data_size,
361  apr_uint32_t timeout,
362  apr_uint16_t flags);
363 /**
364  * Deletes a key from a server
365  * @param mc client to use
366  * @param key null terminated string containing the key
367  * @param timeout time for the delete to stop other clients from adding
368  */
370  const char *key,
371  apr_uint32_t timeout);
372 
373 /**
374  * Increments a value
375  * @param mc client to use
376  * @param key null terminated string containing the key
377  * @param n number to increment by
378  * @param nv new value after incrementing
379  */
381  const char *key,
382  apr_int32_t n,
383  apr_uint32_t *nv);
384 
385 /**
386  * Decrements a value
387  * @param mc client to use
388  * @param key null terminated string containing the key
389  * @param n number to decrement by
390  * @param new_value new value after decrementing
391  */
393  const char *key,
394  apr_int32_t n,
395  apr_uint32_t *new_value);
396 
397 /**
398  * Query a server's version
399  * @param ms server to query
400  * @param p Pool to allocate answer from
401  * @param baton location to store server version string
402  */
404  apr_pool_t *p,
405  char **baton);
406 
407 typedef struct
408 {
409  /** Version string of this server */
410  const char *version;
411  /** Process id of this server process */
412  apr_uint32_t pid;
413  /** Number of seconds this server has been running */
414  apr_uint32_t uptime;
415  /** current UNIX time according to the server */
417  /** The size of a pointer on the current machine */
418  apr_uint32_t pointer_size;
419  /** Accumulated user time for this process */
421  /** Accumulated system time for this process */
423  /** Current number of items stored by the server */
424  apr_uint32_t curr_items;
425  /** Total number of items stored by this server */
426  apr_uint32_t total_items;
427  /** Current number of bytes used by this server to store items */
428  apr_uint64_t bytes;
429  /** Number of open connections */
430  apr_uint32_t curr_connections;
431  /** Total number of connections opened since the server started running */
432  apr_uint32_t total_connections;
433  /** Number of connection structures allocated by the server */
434  apr_uint32_t connection_structures;
435  /** Cumulative number of retrieval requests */
436  apr_uint32_t cmd_get;
437  /** Cumulative number of storage requests */
438  apr_uint32_t cmd_set;
439  /** Number of keys that have been requested and found present */
440  apr_uint32_t get_hits;
441  /** Number of items that have been requested and not found */
442  apr_uint32_t get_misses;
443  /** Number of items removed from cache because they passed their
444  expiration time */
445  apr_uint64_t evictions;
446  /** Total number of bytes read by this server */
447  apr_uint64_t bytes_read;
448  /** Total number of bytes sent by this server */
449  apr_uint64_t bytes_written;
450  /** Number of bytes this server is allowed to use for storage. */
451  apr_uint32_t limit_maxbytes;
452  /** Number of threads the server is running (if built with threading) */
453  apr_uint32_t threads;
455 
456 /**
457  * Query a server for statistics
458  * @param ms server to query
459  * @param p Pool to allocate answer from
460  * @param stats location of the new statistics structure
461  */
463  apr_pool_t *p,
464  apr_memcache_stats_t **stats);
465 
466 
467 /** @} */
468 
469 #ifdef __cplusplus
470 }
471 #endif
472 
473 #endif /* APR_MEMCACHE_H */
APR Platform Definitions.
APR-UTIL Buckets/Bucket Brigades.
APR Hash Tables.
APR Network library.
APR memory allocation.
APR-UTIL Resource List Routines.
APR Rings.
APR Strings library.
APR Time Library.
apr_memcache_server_t * apr_memcache_find_server_hash_default(void *baton, apr_memcache_t *mc, const apr_uint32_t hash)
apr_status_t apr_memcache_replace(apr_memcache_t *mc, const char *key, char *baton, const apr_size_t data_size, apr_uint32_t timeout, apr_uint16_t flags)
apr_uint32_t apr_memcache_hash_crc32(void *baton, const char *data, const apr_size_t data_len)
apr_status_t apr_memcache_version(apr_memcache_server_t *ms, apr_pool_t *p, char **baton)
void apr_memcache_set_retry_period(apr_memcache_t *mc, apr_time_t retry_period)
apr_memcache_server_t * apr_memcache_find_server_hash(apr_memcache_t *mc, const apr_uint32_t hash)
apr_status_t apr_memcache_incr(apr_memcache_t *mc, const char *key, apr_int32_t n, apr_uint32_t *nv)
apr_memcache_server_status_t
Definition: apr_memcache.h:50
apr_status_t apr_memcache_add(apr_memcache_t *mc, const char *key, char *baton, const apr_size_t data_size, apr_uint32_t timeout, apr_uint16_t flags)
apr_status_t apr_memcache_multgetp(apr_memcache_t *mc, apr_pool_t *temp_pool, apr_pool_t *data_pool, apr_hash_t *values)
apr_status_t apr_memcache_server_create(apr_pool_t *p, const char *host, apr_port_t port, int min, int smax, int max, apr_interval_time_t ttl, apr_memcache_server_t **ns)
apr_status_t apr_memcache_create(apr_pool_t *p, apr_uint16_t max_servers, apr_uint32_t flags, apr_memcache_t **mc)
apr_uint32_t apr_memcache_hash_default(void *baton, const char *data, const apr_size_t data_len)
apr_memcache_server_t * apr_memcache_find_server(apr_memcache_t *mc, const char *host, apr_port_t port)
apr_time_t apr_memcache_get_retry_period(apr_memcache_t *mc)
apr_uint32_t apr_memcache_hash(apr_memcache_t *mc, const char *data, const apr_size_t data_len)
apr_status_t apr_memcache_delete(apr_memcache_t *mc, const char *key, apr_uint32_t timeout)
apr_status_t apr_memcache_add_server(apr_memcache_t *mc, apr_memcache_server_t *server)
apr_status_t apr_memcache_set(apr_memcache_t *mc, const char *key, char *baton, const apr_size_t data_size, apr_uint32_t timeout, apr_uint16_t flags)
apr_status_t apr_memcache_getp(apr_memcache_t *mc, apr_pool_t *p, const char *key, char **baton, apr_size_t *len, apr_uint16_t *flags)
struct apr_memcache_conn_t apr_memcache_conn_t
Definition: apr_memcache.h:56
void apr_memcache_add_multget_key(apr_pool_t *data_pool, const char *key, apr_hash_t **values)
apr_status_t apr_memcache_decr(apr_memcache_t *mc, const char *key, apr_int32_t n, apr_uint32_t *new_value)
apr_status_t apr_memcache_stats(apr_memcache_server_t *ms, apr_pool_t *p, apr_memcache_stats_t **stats)
apr_status_t apr_memcache_disable_server(apr_memcache_t *mc, apr_memcache_server_t *ms)
apr_status_t apr_memcache_enable_server(apr_memcache_t *mc, apr_memcache_server_t *ms)
@ APR_MC_SERVER_LIVE
Definition: apr_memcache.h:51
@ APR_MC_SERVER_DEAD
Definition: apr_memcache.h:52
struct apr_reslist_t apr_reslist_t
Definition: apr_reslist.h:42
int apr_status_t
Definition: apr_errno.h:44
struct apr_hash_t apr_hash_t
Definition: apr_hash.h:52
apr_uint16_t apr_port_t
Definition: apr_network_io.h:230
#define APR_DECLARE(type)
Definition: apr.h:516
struct apr_pool_t apr_pool_t
Definition: apr_pools.h:60
struct apr_thread_mutex_t apr_thread_mutex_t
Definition: apr_thread_mutex.h:41
apr_int64_t apr_interval_time_t
Definition: apr_time.h:55
apr_int64_t apr_time_t
Definition: apr_time.h:45
Definition: apr_memcache.h:61
const char * host
Definition: apr_memcache.h:62
apr_reslist_t * conns
Definition: apr_memcache.h:66
apr_memcache_server_status_t status
Definition: apr_memcache.h:64
int min
Definition: apr_memcache.h:77
apr_thread_mutex_t * lock
Definition: apr_memcache.h:72
apr_port_t port
Definition: apr_memcache.h:63
Definition: apr_memcache.h:408
apr_uint32_t pointer_size
Definition: apr_memcache.h:418
apr_uint64_t bytes_written
Definition: apr_memcache.h:449
apr_uint32_t curr_connections
Definition: apr_memcache.h:430
apr_uint32_t total_items
Definition: apr_memcache.h:426
apr_time_t rusage_system
Definition: apr_memcache.h:422
apr_uint64_t bytes
Definition: apr_memcache.h:428
apr_uint32_t total_connections
Definition: apr_memcache.h:432
apr_uint32_t cmd_set
Definition: apr_memcache.h:438
apr_uint32_t threads
Definition: apr_memcache.h:453
apr_time_t rusage_user
Definition: apr_memcache.h:420
const char * version
Definition: apr_memcache.h:410
apr_uint32_t get_hits
Definition: apr_memcache.h:440
apr_uint32_t pid
Definition: apr_memcache.h:412
apr_uint32_t cmd_get
Definition: apr_memcache.h:436
apr_uint32_t curr_items
Definition: apr_memcache.h:424
apr_uint32_t connection_structures
Definition: apr_memcache.h:434
apr_uint64_t bytes_read
Definition: apr_memcache.h:447
apr_uint64_t evictions
Definition: apr_memcache.h:445
apr_time_t time
Definition: apr_memcache.h:416
apr_uint32_t uptime
Definition: apr_memcache.h:414
apr_uint32_t limit_maxbytes
Definition: apr_memcache.h:451
apr_uint32_t get_misses
Definition: apr_memcache.h:442
Definition: apr_memcache.h:106
void * hash_baton
Definition: apr_memcache.h:112
apr_time_t retry_period
Definition: apr_memcache.h:117
apr_memcache_server_t ** live_servers
Definition: apr_memcache.h:110
apr_uint16_t ntotal
Definition: apr_memcache.h:109
apr_uint16_t nalloc
Definition: apr_memcache.h:108
apr_uint32_t flags
Definition: apr_memcache.h:107
Definition: apr_memcache.h:122