Apache Portable Runtime
Loading...
Searching...
No Matches
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
39extern "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 */
49typedef 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
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*/
89typedef apr_uint32_t (*apr_memcache_hash_func)(void *baton,
90 const char *data,
91 const apr_size_t data_len);
92
93typedef 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*/
100typedef 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 */
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 */
121typedef 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 */
145APR_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 */
152APR_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,
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
407typedef 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 */
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_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_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_memcache_server_t * apr_memcache_find_server(apr_memcache_t *mc, const char *host, apr_port_t port)
apr_status_t apr_memcache_create(apr_pool_t *p, apr_uint16_t max_servers, apr_uint32_t flags, apr_memcache_t **mc)
apr_memcache_server_t * apr_memcache_find_server_hash(apr_memcache_t *mc, const apr_uint32_t hash)
apr_uint32_t apr_memcache_hash_default(void *baton, const char *data, const apr_size_t data_len)
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_memcache_server_t * apr_memcache_find_server_hash_default(void *baton, apr_memcache_t *mc, const apr_uint32_t hash)
@ 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