Apache Portable Runtime
apr_memcache.h
Go to the documentation of this file.
00001 /* Licensed to the Apache Software Foundation (ASF) under one or more
00002  * contributor license agreements.  See the NOTICE file distributed with
00003  * this work for additional information regarding copyright ownership.
00004  * The ASF licenses this file to You under the Apache License, Version 2.0
00005  * (the "License"); you may not use this file except in compliance with
00006  * the License.  You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef APR_MEMCACHE_H
00018 #define APR_MEMCACHE_H
00019 
00020 /**
00021  * @file apr_memcache.h
00022  * @brief Client interface for memcached
00023  * @remark To use this interface you must have a separate memcached
00024  * server running. See the memcached website at http://www.danga.com/memcached/
00025  * for more information.
00026  */
00027 
00028 #include "apr.h"
00029 #include "apr_pools.h"
00030 #include "apr_time.h"
00031 #include "apr_strings.h"
00032 #include "apr_network_io.h"
00033 #include "apr_buckets.h"
00034 #include "apr_ring.h"
00035 #include "apr_reslist.h"
00036 #include "apr_hash.h"
00037 
00038 #ifdef __cplusplus
00039 extern "C" {
00040 #endif /* __cplusplus */
00041 
00042 /**
00043  * @defgroup APR_Util_MC Memcached Client Routines
00044  * @ingroup APR
00045  * @{
00046  */
00047 
00048 /** Specifies the status of a memcached server */
00049 typedef enum
00050 {
00051     APR_MC_SERVER_LIVE, /**< Server is alive and responding to requests */
00052     APR_MC_SERVER_DEAD  /**< Server is not responding to requests */
00053 } apr_memcache_server_status_t;
00054 
00055 /** Opaque memcache client connection object */
00056 typedef struct apr_memcache_conn_t apr_memcache_conn_t;
00057 
00058 /** Memcache Server Info Object */
00059 typedef struct apr_memcache_server_t apr_memcache_server_t;
00060 struct apr_memcache_server_t
00061 {
00062     const char *host; /**< Hostname of this Server */
00063     apr_port_t port; /**< Port of this Server */
00064     apr_memcache_server_status_t status; /**< @see apr_memcache_server_status_t */
00065 #if APR_HAS_THREADS || defined(DOXYGEN)
00066     apr_reslist_t *conns; /**< Resource list of actual client connections */
00067 #else
00068     apr_memcache_conn_t *conn;
00069 #endif
00070     apr_pool_t *p; /** Pool to use for private allocations */
00071 #if APR_HAS_THREADS
00072     apr_thread_mutex_t *lock;
00073 #endif
00074     apr_time_t btime;
00075 };
00076 
00077 /* Custom hash callback function prototype, user for server selection.
00078 * @param baton user selected baton
00079 * @param data data to hash
00080 * @param data_len length of data
00081 */
00082 typedef apr_uint32_t (*apr_memcache_hash_func)(void *baton,
00083                                                const char *data,
00084                                                const apr_size_t data_len);
00085 
00086 typedef struct apr_memcache_t apr_memcache_t;
00087 
00088 /* Custom Server Select callback function prototype.
00089 * @param baton user selected baton
00090 * @param mc memcache instance, use mc->live_servers to select a node
00091 * @param hash hash of the selected key.
00092 */
00093 typedef apr_memcache_server_t* (*apr_memcache_server_func)(void *baton,
00094                                                  apr_memcache_t *mc,
00095                                                  const apr_uint32_t hash);
00096 
00097 /** Container for a set of memcached servers */
00098 struct apr_memcache_t
00099 {
00100     apr_uint32_t flags; /**< Flags, Not currently used */
00101     apr_uint16_t nalloc; /**< Number of Servers Allocated */
00102     apr_uint16_t ntotal; /**< Number of Servers Added */
00103     apr_memcache_server_t **live_servers; /**< Array of Servers */
00104     apr_pool_t *p; /** Pool to use for allocations */
00105     void *hash_baton;
00106     apr_memcache_hash_func hash_func;
00107     void *server_baton;
00108     apr_memcache_server_func server_func;
00109 };
00110 
00111 /** Returned Data from a multiple get */
00112 typedef struct
00113 {
00114     apr_status_t status;
00115     const char* key;
00116     apr_size_t len;
00117     char *data;
00118     apr_uint16_t flags;
00119 } apr_memcache_value_t;
00120 
00121 /**
00122  * Creates a crc32 hash used to split keys between servers
00123  * @param mc The memcache client object to use
00124  * @param data Data to be hashed
00125  * @param data_len Length of the data to use
00126  * @return crc32 hash of data
00127  * @remark The crc32 hash is not compatible with old memcached clients.
00128  */
00129 APR_DECLARE(apr_uint32_t) apr_memcache_hash(apr_memcache_t *mc,
00130                                             const char *data,
00131                                             const apr_size_t data_len);
00132 
00133 /**
00134  * Pure CRC32 Hash. Used by some clients.
00135  */
00136 APR_DECLARE(apr_uint32_t) apr_memcache_hash_crc32(void *baton,
00137                                                   const char *data,
00138                                                   const apr_size_t data_len);
00139 
00140 /**
00141  * hash compatible with the standard Perl Client.
00142  */
00143 APR_DECLARE(apr_uint32_t) apr_memcache_hash_default(void *baton,
00144                                                     const char *data,
00145                                                     const apr_size_t data_len);
00146 
00147 /**
00148  * Picks a server based on a hash
00149  * @param mc The memcache client object to use
00150  * @param hash Hashed value of a Key
00151  * @return server that controls specified hash
00152  * @see apr_memcache_hash
00153  */
00154 APR_DECLARE(apr_memcache_server_t *) apr_memcache_find_server_hash(apr_memcache_t *mc, 
00155                                                                    const apr_uint32_t hash);
00156 
00157 /**
00158  * server selection compatible with the standard Perl Client.
00159  */
00160 APR_DECLARE(apr_memcache_server_t *)
00161 apr_memcache_find_server_hash_default(void *baton,
00162                                       apr_memcache_t *mc, 
00163                                       const apr_uint32_t hash);
00164 
00165 /**
00166  * Adds a server to a client object
00167  * @param mc The memcache client object to use
00168  * @param server Server to add
00169  * @remark Adding servers is not thread safe, and should be done once at startup.
00170  * @warning Changing servers after startup may cause keys to go to
00171  * different servers.
00172  */
00173 APR_DECLARE(apr_status_t) apr_memcache_add_server(apr_memcache_t *mc,
00174                                                   apr_memcache_server_t *server);
00175 
00176 
00177 /**
00178  * Finds a Server object based on a hostname/port pair
00179  * @param mc The memcache client object to use
00180  * @param host Hostname of the server
00181  * @param port Port of the server
00182  * @return Server with matching Hostname and Port, or NULL if none was found.
00183  */
00184 APR_DECLARE(apr_memcache_server_t *) apr_memcache_find_server(apr_memcache_t *mc,
00185                                                               const char *host,
00186                                                               apr_port_t port);
00187 
00188 /**
00189  * Enables a Server for use again
00190  * @param mc The memcache client object to use
00191  * @param ms Server to Activate
00192  */
00193 APR_DECLARE(apr_status_t) apr_memcache_enable_server(apr_memcache_t *mc,
00194                                                      apr_memcache_server_t *ms);
00195 
00196 
00197 /**
00198  * Disable a Server
00199  * @param mc The memcache client object to use
00200  * @param ms Server to Disable
00201  */
00202 APR_DECLARE(apr_status_t) apr_memcache_disable_server(apr_memcache_t *mc,
00203                                                       apr_memcache_server_t *ms);
00204 
00205 /**
00206  * Creates a new Server Object
00207  * @param p Pool to use
00208  * @param host hostname of the server
00209  * @param port port of the server
00210  * @param min  minimum number of client sockets to open
00211  * @param smax soft maximum number of client connections to open
00212  * @param max  hard maximum number of client connections
00213  * @param ttl  time to live in microseconds of a client connection
00214  * @param ns   location of the new server object
00215  * @see apr_reslist_create
00216  * @remark min, smax, and max are only used when APR_HAS_THREADS
00217  */
00218 APR_DECLARE(apr_status_t) apr_memcache_server_create(apr_pool_t *p,
00219                                                      const char *host,
00220                                                      apr_port_t port,
00221                                                      apr_uint32_t min,
00222                                                      apr_uint32_t smax,
00223                                                      apr_uint32_t max,
00224                                                      apr_uint32_t ttl,
00225                                                      apr_memcache_server_t **ns);
00226 /**
00227  * Creates a new memcached client object
00228  * @param p Pool to use
00229  * @param max_servers maximum number of servers
00230  * @param flags Not currently used
00231  * @param mc   location of the new memcache client object
00232  */
00233 APR_DECLARE(apr_status_t) apr_memcache_create(apr_pool_t *p,
00234                                               apr_uint16_t max_servers,
00235                                               apr_uint32_t flags,
00236                                               apr_memcache_t **mc);
00237 
00238 /**
00239  * Gets a value from the server, allocating the value out of p
00240  * @param mc client to use
00241  * @param p Pool to use
00242  * @param key null terminated string containing the key
00243  * @param baton location of the allocated value
00244  * @param len   length of data at baton
00245  * @param flags any flags set by the client for this key
00246  * @return 
00247  */
00248 APR_DECLARE(apr_status_t) apr_memcache_getp(apr_memcache_t *mc, 
00249                                             apr_pool_t *p,
00250                                             const char* key,
00251                                             char **baton,
00252                                             apr_size_t *len,
00253                                             apr_uint16_t *flags);
00254 
00255 
00256 /**
00257  * Add a key to a hash for a multiget query
00258  *  if the hash (*value) is NULL it will be created
00259  * @param data_pool pool from where the hash and their items are created from
00260  * @param key null terminated string containing the key
00261  * @param values hash of keys and values that this key will be added to
00262  * @return
00263  */
00264 APR_DECLARE(void) apr_memcache_add_multget_key(apr_pool_t *data_pool,
00265                                                const char* key,
00266                                                apr_hash_t **values);
00267 
00268 /**
00269  * Gets multiple values from the server, allocating the values out of p
00270  * @param mc client to use
00271  * @param temp_pool Pool used for temporary allocations. May be cleared inside this
00272  *        call.
00273  * @param data_pool Pool used to allocate data for the returned values.
00274  * @param values hash of apr_memcache_value_t keyed by strings, contains the
00275  *        result of the multiget call.
00276  * @return
00277  */
00278 APR_DECLARE(apr_status_t) apr_memcache_multgetp(apr_memcache_t *mc,
00279                                                 apr_pool_t *temp_pool,
00280                                                 apr_pool_t *data_pool,
00281                                                 apr_hash_t *values);
00282 
00283 /**
00284  * Sets a value by key on the server
00285  * @param mc client to use
00286  * @param key   null terminated string containing the key
00287  * @param baton data to store on the server
00288  * @param data_size   length of data at baton
00289  * @param timeout time in seconds for the data to live on the server
00290  * @param flags any flags set by the client for this key
00291  */
00292 APR_DECLARE(apr_status_t) apr_memcache_set(apr_memcache_t *mc,
00293                                            const char *key,
00294                                            char *baton,
00295                                            const apr_size_t data_size,
00296                                            apr_uint32_t timeout,
00297                                            apr_uint16_t flags);
00298 
00299 /**
00300  * Adds value by key on the server
00301  * @param mc client to use
00302  * @param key   null terminated string containing the key
00303  * @param baton data to store on the server
00304  * @param data_size   length of data at baton
00305  * @param timeout time for the data to live on the server
00306  * @param flags any flags set by the client for this key
00307  * @return APR_SUCCESS if the key was added, APR_EEXIST if the key 
00308  * already exists on the server.
00309  */
00310 APR_DECLARE(apr_status_t) apr_memcache_add(apr_memcache_t *mc,
00311                                            const char *key,
00312                                            char *baton,
00313                                            const apr_size_t data_size,
00314                                            apr_uint32_t timeout,
00315                                            apr_uint16_t flags);
00316 
00317 /**
00318  * Replaces value by key on the server
00319  * @param mc client to use
00320  * @param key   null terminated string containing the key
00321  * @param baton data to store on the server
00322  * @param data_size   length of data at baton
00323  * @param timeout time for the data to live on the server
00324  * @param flags any flags set by the client for this key
00325  * @return APR_SUCCESS if the key was added, APR_EEXIST if the key 
00326  * did not exist on the server.
00327  */
00328 APR_DECLARE(apr_status_t) apr_memcache_replace(apr_memcache_t *mc,
00329                                                const char *key,
00330                                                char *baton,
00331                                                const apr_size_t data_size,
00332                                                apr_uint32_t timeout,
00333                                                apr_uint16_t flags);
00334 /**
00335  * Deletes a key from a server
00336  * @param mc client to use
00337  * @param key   null terminated string containing the key
00338  * @param timeout time for the delete to stop other clients from adding
00339  */
00340 APR_DECLARE(apr_status_t) apr_memcache_delete(apr_memcache_t *mc,
00341                                               const char *key,
00342                                               apr_uint32_t timeout);
00343 
00344 /**
00345  * Increments a value
00346  * @param mc client to use
00347  * @param key   null terminated string containing the key
00348  * @param n     number to increment by
00349  * @param nv    new value after incrementing
00350  */
00351 APR_DECLARE(apr_status_t) apr_memcache_incr(apr_memcache_t *mc, 
00352                                             const char *key,
00353                                             apr_int32_t n,
00354                                             apr_uint32_t *nv);
00355 
00356 /**
00357  * Decrements a value
00358  * @param mc client to use
00359  * @param key   null terminated string containing the key
00360  * @param n     number to decrement by
00361  * @param new_value    new value after decrementing
00362  */
00363 APR_DECLARE(apr_status_t) apr_memcache_decr(apr_memcache_t *mc, 
00364                                             const char *key,
00365                                             apr_int32_t n,
00366                                             apr_uint32_t *new_value);
00367 
00368 /**
00369  * Query a server's version
00370  * @param ms    server to query
00371  * @param p     Pool to allocate answer from
00372  * @param baton location to store server version string
00373  * @param len   length of the server version string
00374  */
00375 APR_DECLARE(apr_status_t) apr_memcache_version(apr_memcache_server_t *ms,
00376                                                apr_pool_t *p,
00377                                                char **baton);
00378 
00379 typedef struct
00380 {
00381     /** Version string of this server */
00382     const char *version;
00383     /** Process id of this server process */
00384     apr_uint32_t pid;
00385     /** Number of seconds this server has been running */
00386     apr_uint32_t uptime;
00387     /** current UNIX time according to the server */
00388     apr_time_t time;
00389     /** The size of a pointer on the current machine */
00390     apr_uint32_t pointer_size;
00391     /** Accumulated user time for this process */
00392     apr_time_t rusage_user;
00393     /** Accumulated system time for this process */
00394     apr_time_t rusage_system;
00395     /** Current number of items stored by the server */
00396     apr_uint32_t curr_items;
00397     /** Total number of items stored by this server */
00398     apr_uint32_t total_items;
00399     /** Current number of bytes used by this server to store items */
00400     apr_uint64_t bytes;
00401     /** Number of open connections */
00402     apr_uint32_t curr_connections;
00403     /** Total number of connections opened since the server started running */
00404     apr_uint32_t total_connections;
00405     /** Number of connection structures allocated by the server */
00406     apr_uint32_t connection_structures;
00407     /** Cumulative number of retrieval requests */
00408     apr_uint32_t cmd_get;
00409     /** Cumulative number of storage requests */
00410     apr_uint32_t cmd_set;
00411     /** Number of keys that have been requested and found present */
00412     apr_uint32_t get_hits;
00413     /** Number of items that have been requested and not found */
00414     apr_uint32_t get_misses;
00415     /** Number of items removed from cache because they passed their
00416         expiration time */
00417     apr_uint64_t evictions;
00418     /** Total number of bytes read by this server */
00419     apr_uint64_t bytes_read;
00420     /** Total number of bytes sent by this server */
00421     apr_uint64_t bytes_written;
00422     /** Number of bytes this server is allowed to use for storage. */
00423     apr_uint32_t limit_maxbytes;
00424     /** Number of threads the server is running (if built with threading) */
00425     apr_uint32_t threads; 
00426 } apr_memcache_stats_t;
00427 
00428 /**
00429  * Query a server for statistics
00430  * @param ms    server to query
00431  * @param p     Pool to allocate answer from
00432  * @param stats location of the new statistics structure
00433  */
00434 APR_DECLARE(apr_status_t) apr_memcache_stats(apr_memcache_server_t *ms, 
00435                                              apr_pool_t *p,
00436                                              apr_memcache_stats_t **stats);
00437 
00438 
00439 /** @} */
00440 
00441 #ifdef __cplusplus
00442 }
00443 #endif
00444 
00445 #endif /* APR_MEMCACHE_H */
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Defines