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 39extern "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 */ 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 */ 53} apr_memcache_server_status_t; 54 55/** Opaque memcache client connection object */ 56typedef struct apr_memcache_conn_t apr_memcache_conn_t; 57 58/** Memcache Server Info Object */ 59typedef struct apr_memcache_server_t apr_memcache_server_t; 60struct apr_memcache_server_t 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 72 apr_thread_mutex_t *lock; 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*/ 82typedef apr_uint32_t (*apr_memcache_hash_func)(void *baton, 83 const char *data, 84 const apr_size_t data_len); 85 86typedef 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*/ 93typedef 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 */ 98struct apr_memcache_t 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 */ 112typedef struct 113{ 114 apr_status_t status; 115 const char* key; 116 apr_size_t len; 117 char *data; 118 apr_uint16_t flags; 119} apr_memcache_value_t; 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 */ 129APU_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 */ 136APU_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 */ 143APU_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 */ 154APU_DECLARE(apr_memcache_server_t *) apr_memcache_find_server_hash(apr_memcache_t *mc, 155 const apr_uint32_t hash); 156 157/** 158 * server selection compatible with the standard Perl Client. 159 */ 160APU_DECLARE(apr_memcache_server_t *) apr_memcache_find_server_hash_default(void *baton, 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 */ 172APU_DECLARE(apr_status_t) apr_memcache_add_server(apr_memcache_t *mc, 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 */ 183APU_DECLARE(apr_memcache_server_t *) apr_memcache_find_server(apr_memcache_t *mc, 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 */ 192APU_DECLARE(apr_status_t) apr_memcache_enable_server(apr_memcache_t *mc, 193 apr_memcache_server_t *ms); 194 195 196/** 197 * Disable a Server 198 * @param mc The memcache client object to use 199 * @param ms Server to Disable 200 */ 201APU_DECLARE(apr_status_t) apr_memcache_disable_server(apr_memcache_t *mc, 202 apr_memcache_server_t *ms); 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 */ 217APU_DECLARE(apr_status_t) apr_memcache_server_create(apr_pool_t *p, 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 */ 232APU_DECLARE(apr_status_t) apr_memcache_create(apr_pool_t *p, 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 */ 247APU_DECLARE(apr_status_t) apr_memcache_getp(apr_memcache_t *mc, 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 */ 263APU_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 */ 277APU_DECLARE(apr_status_t) apr_memcache_multgetp(apr_memcache_t *mc, 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 */ 291APU_DECLARE(apr_status_t) apr_memcache_set(apr_memcache_t *mc, 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 */ 309APU_DECLARE(apr_status_t) apr_memcache_add(apr_memcache_t *mc, 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 */ 327APU_DECLARE(apr_status_t) apr_memcache_replace(apr_memcache_t *mc, 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 */ 339APU_DECLARE(apr_status_t) apr_memcache_delete(apr_memcache_t *mc, 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 */ 350APU_DECLARE(apr_status_t) apr_memcache_incr(apr_memcache_t *mc, 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 */ 362APU_DECLARE(apr_status_t) apr_memcache_decr(apr_memcache_t *mc, 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 */ 374APU_DECLARE(apr_status_t) apr_memcache_version(apr_memcache_server_t *ms, 375 apr_pool_t *p, 376 char **baton); 377 378typedef 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 */ 387 apr_time_t time; 388 /** The size of a pointer on the current machine */ 389 apr_uint32_t pointer_size; 390 /** Accumulated user time for this process */ 391 apr_time_t rusage_user; 392 /** Accumulated system time for this process */ 393 apr_time_t rusage_system; 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; 425} apr_memcache_stats_t; 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 */ 433APU_DECLARE(apr_status_t) apr_memcache_stats(apr_memcache_server_t *ms, 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 */ 445