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 data Data to be hashed
 124  * @param data_len Length of the data to use
 125  * @return crc32 hash of data
 126  * @remark The crc32 hash is not compatible with old memcached clients.
 127  */
 128 APU_DECLARE(apr_uint32_t) apr_memcache_hash(apr_memcache_t *mc,
 129                                             const char *data,
 130                                             const apr_size_t data_len);
 131
 132 /**
 133  * Pure CRC32 Hash. Used by some clients.
 134  */
 135 APU_DECLARE(apr_uint32_t) apr_memcache_hash_crc32(void *baton,
 136                                                   const char *data,
 137                                                   const apr_size_t data_len);
 138
 139 /**
 140  * hash compatible with the standard Perl Client.
 141  */
 142 APU_DECLARE(apr_uint32_t) apr_memcache_hash_default(void *baton,
 143                                                     const char *data,
 144                                                     const apr_size_t data_len);
 145
 146 /**
 147  * Picks a server based on a hash
 148  * @param mc The memcache client object to use
 149  * @param hash Hashed value of a Key
 150  * @return server that controls specified hash
 151  * @see apr_memcache_hash
 152  */
 153 APU_DECLARE(apr_memcache_server_t *) apr_memcache_find_server_hash(apr_memcache_t *mc,
 154                                                                    const apr_uint32_t hash);
 155
 156 /**
 157  * server selection compatible with the standard Perl Client.
 158  */
 159 APU_DECLARE(apr_memcache_server_t *)
 160 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 ms 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 seconds 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)
 264 apr_memcache_add_multget_key(apr_pool_t *data_pool,
 265                              const char* key,
 266                              apr_hash_t **values);
 267
 268 /**
 269  * Gets multiple values from the server, allocating the values out of p
 270  * @param mc client to use
 271  * @param temp_pool Pool used for tempoary allocations. May be cleared inside this
 272  *        call.
 273  * @param data_pool Pool used to allocate data for the returned values.
 274  * @param values hash of apr_memcache_value_t keyed by strings, contains the
 275  *        result of the multiget call.
 276  * @return
 277  */
 278 APU_DECLARE(apr_status_t)
 279 apr_memcache_multgetp(apr_memcache_t *mc,
 280                       apr_pool_t *temp_pool,
 281                       apr_pool_t *data_pool,
 282                       apr_hash_t *values);
 283
 284 /**
 285  * Sets a value by key on the server
 286  * @param mc client to use
 287  * @param key   null terminated string containing the key
 288  * @param baton data to store on the server
 289  * @param len   length of data at baton
 290  * @param timeout time in seconds for the data to live on the server
 291  * @param flags any flags set by the client for this key
 292  */
 293 APU_DECLARE(apr_status_t) apr_memcache_set(apr_memcache_t *mc,
 294                                            const char *key,
 295                                            char *baton,
 296                                            const apr_size_t data_size,
 297                                            apr_uint32_t timeout,
 298                                            apr_uint16_t flags);
 299
 300 /**
 301  * Adds value by key on the server
 302  * @param mc client to use
 303  * @param key   null terminated string containing the key
 304  * @param baton data to store on the server
 305  * @param len   length of data at baton
 306  * @param timeout time for the data to live on the server
 307  * @param flags any flags set by the client for this key
 308  * @return APR_SUCCESS if the key was added, APR_EEXIST if the key
 309  * already exists on the server.
 310  */
 311 APU_DECLARE(apr_status_t) apr_memcache_add(apr_memcache_t *mc,
 312                                            const char *key,
 313                                            char *baton,
 314                                            const apr_size_t data_size,
 315                                            apr_uint32_t timeout,
 316                                            apr_uint16_t flags);
 317
 318 /**
 319  * Replaces value by key on the server
 320  * @param mc client to use
 321  * @param key   null terminated string containing the key
 322  * @param baton data to store on the server
 323  * @param len   length of data at baton
 324  * @param timeout time for the data to live on the server
 325  * @param flags any flags set by the client for this key
 326  * @return APR_SUCCESS if the key was added, APR_EEXIST if the key
 327  * did not exist on the server.
 328  */
 329 APU_DECLARE(apr_status_t) apr_memcache_replace(apr_memcache_t *mc,
 330                                                const char *key,
 331                                                char *data,
 332                                                const apr_size_t data_size,
 333                                                apr_uint32_t timeout,
 334                                                apr_uint16_t flags);
 335 /**
 336  * Deletes a key from a server
 337  * @param mc client to use
 338  * @param key   null terminated string containing the key
 339  * @param timeout time for the delete to stop other clients from adding
 340  */
 341 APU_DECLARE(apr_status_t) apr_memcache_delete(apr_memcache_t *mc,
 342                                               const char *key,
 343                                               apr_uint32_t timeout);
 344
 345 /**
 346  * Increments a value
 347  * @param mc client to use
 348  * @param key   null terminated string containing the key
 349  * @param n     number to increment by
 350  * @param nv    new value after incrmenting
 351  */
 352 APU_DECLARE(apr_status_t) apr_memcache_incr(apr_memcache_t *mc,
 353                                             const char *key,
 354                                             apr_int32_t n,
 355                                             apr_uint32_t *nv);
 356
 357 /**
 358  * Decrements a value
 359  * @param mc client to use
 360  * @param key   null terminated string containing the key
 361  * @param n     number to decrement by
 362  * @param nv    new value after decrementing
 363  */
 364 APU_DECLARE(apr_status_t) apr_memcache_decr(apr_memcache_t *mc,
 365                                             const char *key,
 366                                             apr_int32_t n,
 367                                             apr_uint32_t *new_value);
 368
 369 /**
 370  * Query a server's version
 371  * @param ms    server to query
 372  * @param p     Pool to allocate answer from
 373  * @param baton location to store server version string
 374  * @param len   length of the server version string
 375  */
 376 APU_DECLARE(apr_status_t) apr_memcache_version(apr_memcache_server_t *ms,
 377                                                apr_pool_t *p,
 378                                                char **baton);
 379
 380 typedef struct
 381 {
 382     /** Version string of this server */
 383     const char *version;
 384     /** Process id of this server process */
 385     apr_uint32_t pid;
 386     /** Number of seconds this server has been running */
 387     apr_uint32_t uptime;
 388     /** current UNIX time according to the server */
 389     apr_time_t time;
 390     /** The size of a pointer on the current machine */
 391     apr_uint32_t pointer_size;
 392     /** Accumulated user time for this process */
 393     apr_time_t rusage_user;
 394     /** Accumulated system time for this process */
 395     apr_time_t rusage_system;
 396     /** Current number of items stored by the server */
 397     apr_uint32_t curr_items;
 398     /** Total number of items stored by this server */
 399     apr_uint32_t total_items;
 400     /** Current number of bytes used by this server to store items */
 401     apr_uint64_t bytes;
 402     /** Number of open connections */
 403     apr_uint32_t curr_connections;
 404     /** Total number of connections opened since the server started running */
 405     apr_uint32_t total_connections;
 406     /** Number of connection structures allocated by the server */
 407     apr_uint32_t connection_structures;
 408     /** Cumulative number of retrieval requests */
 409     apr_uint32_t cmd_get;
 410     /** Cumulative number of storage requests */
 411     apr_uint32_t cmd_set;
 412     /** Number of keys that have been requested and found present */
 413     apr_uint32_t get_hits;
 414     /** Number of items that have been requested and not found */
 415     apr_uint32_t get_misses;
 416     /** Number of items removed from cache because they passed their
 417         expiration time */
 418     apr_uint64_t evictions;
 419     /** Total number of bytes read by this server */
 420     apr_uint64_t bytes_read;
 421     /** Total number of bytes sent by this server */
 422     apr_uint64_t bytes_written;
 423     /** Number of bytes this server is allowed to use for storage. */
 424     apr_uint32_t limit_maxbytes;
 425     /** Number of threads the server is running (if built with threading) */
 426     apr_uint32_t threads;
 427 } apr_memcache_stats_t;
 428
 429 /**
 430  * Query a server for statistics
 431  * @param ms    server to query
 432  * @param p     Pool to allocate answer from
 433  * @param stats location of the new statistics structure
 434  */
 435 APU_DECLARE(apr_status_t) apr_memcache_stats(apr_memcache_server_t *ms,
 436                                              apr_pool_t *p,
 437                                              apr_memcache_stats_t **stats);
 438
 439
 440 /** @} */
 441
 442 #ifdef __cplusplus
 443 }
 444 #endif
 445
 446 #endif /* APR_MEMCACHE_H */