contrib/apr-util/include/apr_memcache.h

   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 */
  53 } apr_memcache_server_status_t;
  54
  55 /** Opaque memcache client connection object */
  56 typedef struct apr_memcache_conn_t apr_memcache_conn_t;
  57
  58 /** Memcache Server Info Object */
  59 typedef struct apr_memcache_server_t apr_memcache_server_t;
  60 struct 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 */
  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 */
  98 struct 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 */
 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;
 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  */
 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  */
 154 APU_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  */
 160 APU_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  */
 172 APU_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  */
 183 APU_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  */
 192 APU_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  */
 201 APU_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  */
 217 APU_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  */
 232 APU_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  */
 247 APU_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  */
 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  */
 277 APU_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  */
 291 APU_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  */
 309 APU_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  */
 327 APU_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  */
 339 APU_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  */
 350 APU_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  */
 362 APU_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  */
 374 APU_DECLARE(apr_status_t) apr_memcache_version(apr_memcache_server_t *ms,
 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 */
 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  */
 433 APU_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 */