/* Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ #ifndef APR_MEMCACHE_H #define APR_MEMCACHE_H /** * @file apr_memcache.h * @brief Client interface for memcached * @remark To use this interface you must have a separate memcached * server running. See the memcached website at http://www.danga.com/memcached/ * for more information. */ #include "apr.h" #include "apr_pools.h" #include "apr_time.h" #include "apr_strings.h" #include "apr_network_io.h" #include "apr_ring.h" #include "apr_buckets.h" #include "apr_reslist.h" #include "apr_hash.h" #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ /** * @defgroup APR_Util_MC Memcached Client Routines * @ingroup APR_Util * @{ */ /** Specifies the status of a memcached server */ typedef enum { APR_MC_SERVER_LIVE, /**< Server is alive and responding to requests */ APR_MC_SERVER_DEAD /**< Server is not responding to requests */ } apr_memcache_server_status_t; /** Opaque memcache client connection object */ typedef struct apr_memcache_conn_t apr_memcache_conn_t; /** Memcache Server Info Object */ typedef struct apr_memcache_server_t apr_memcache_server_t; struct apr_memcache_server_t { const char *host; /**< Hostname of this Server */ apr_port_t port; /**< Port of this Server */ apr_memcache_server_status_t status; /**< @see apr_memcache_server_status_t */ #if APR_HAS_THREADS || defined(DOXYGEN) apr_reslist_t *conns; /**< Resource list of actual client connections */ #else apr_memcache_conn_t *conn; #endif apr_pool_t *p; /** Pool to use for private allocations */ #if APR_HAS_THREADS apr_thread_mutex_t *lock; #endif apr_time_t btime; }; /* Custom hash callback function prototype, user for server selection. * @param baton user selected baton * @param data data to hash * @param data_len length of data */ typedef apr_uint32_t (*apr_memcache_hash_func)(void *baton, const char *data, const apr_size_t data_len); typedef struct apr_memcache_t apr_memcache_t; /* Custom Server Select callback function prototype. * @param baton user selected baton * @param mc memcache instance, use mc->live_servers to select a node * @param hash hash of the selected key. */ typedef apr_memcache_server_t* (*apr_memcache_server_func)(void *baton, apr_memcache_t *mc, const apr_uint32_t hash); /** Container for a set of memcached servers */ struct apr_memcache_t { apr_uint32_t flags; /**< Flags, Not currently used */ apr_uint16_t nalloc; /**< Number of Servers Allocated */ apr_uint16_t ntotal; /**< Number of Servers Added */ apr_memcache_server_t **live_servers; /**< Array of Servers */ apr_pool_t *p; /** Pool to use for allocations */ void *hash_baton; apr_memcache_hash_func hash_func; void *server_baton; apr_memcache_server_func server_func; }; /** Returned Data from a multiple get */ typedef struct { apr_status_t status; const char* key; apr_size_t len; char *data; apr_uint16_t flags; } apr_memcache_value_t; /** * Creates a crc32 hash used to split keys between servers * @param mc The memcache client object to use * @param data Data to be hashed * @param data_len Length of the data to use * @return crc32 hash of data * @remark The crc32 hash is not compatible with old memcached clients. */ APU_DECLARE(apr_uint32_t) apr_memcache_hash(apr_memcache_t *mc, const char *data, const apr_size_t data_len); /** * Pure CRC32 Hash. Used by some clients. */ APU_DECLARE(apr_uint32_t) apr_memcache_hash_crc32(void *baton, const char *data, const apr_size_t data_len); /** * hash compatible with the standard Perl Client. */ APU_DECLARE(apr_uint32_t) apr_memcache_hash_default(void *baton, const char *data, const apr_size_t data_len); /** * Picks a server based on a hash * @param mc The memcache client object to use * @param hash Hashed value of a Key * @return server that controls specified hash * @see apr_memcache_hash */ APU_DECLARE(apr_memcache_server_t *) apr_memcache_find_server_hash(apr_memcache_t *mc, const apr_uint32_t hash); /** * server selection compatible with the standard Perl Client. */ APU_DECLARE(apr_memcache_server_t *) apr_memcache_find_server_hash_default(void *baton, apr_memcache_t *mc, const apr_uint32_t hash); /** * Adds a server to a client object * @param mc The memcache client object to use * @param server Server to add * @remark Adding servers is not thread safe, and should be done once at startup. * @warning Changing servers after startup may cause keys to go to * different servers. */ APU_DECLARE(apr_status_t) apr_memcache_add_server(apr_memcache_t *mc, apr_memcache_server_t *server); /** * Finds a Server object based on a hostname/port pair * @param mc The memcache client object to use * @param host Hostname of the server * @param port Port of the server * @return Server with matching Hostname and Port, or NULL if none was found. */ APU_DECLARE(apr_memcache_server_t *) apr_memcache_find_server(apr_memcache_t *mc, const char *host, apr_port_t port); /** * Enables a Server for use again * @param mc The memcache client object to use * @param ms Server to Activate */ APU_DECLARE(apr_status_t) apr_memcache_enable_server(apr_memcache_t *mc, apr_memcache_server_t *ms); /** * Disable a Server * @param mc The memcache client object to use * @param ms Server to Disable */ APU_DECLARE(apr_status_t) apr_memcache_disable_server(apr_memcache_t *mc, apr_memcache_server_t *ms); /** * Creates a new Server Object * @param p Pool to use * @param host hostname of the server * @param port port of the server * @param min minimum number of client sockets to open * @param smax soft maximum number of client connections to open * @param max hard maximum number of client connections * @param ttl time to live in microseconds of a client connection * @param ns location of the new server object * @see apr_reslist_create * @remark min, smax, and max are only used when APR_HAS_THREADS */ APU_DECLARE(apr_status_t) apr_memcache_server_create(apr_pool_t *p, const char *host, apr_port_t port, apr_uint32_t min, apr_uint32_t smax, apr_uint32_t max, apr_uint32_t ttl, apr_memcache_server_t **ns); /** * Creates a new memcached client object * @param p Pool to use * @param max_servers maximum number of servers * @param flags Not currently used * @param mc location of the new memcache client object */ APU_DECLARE(apr_status_t) apr_memcache_create(apr_pool_t *p, apr_uint16_t max_servers, apr_uint32_t flags, apr_memcache_t **mc); /** * Gets a value from the server, allocating the value out of p * @param mc client to use * @param p Pool to use * @param key null terminated string containing the key * @param baton location of the allocated value * @param len length of data at baton * @param flags any flags set by the client for this key * @return */ APU_DECLARE(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); /** * Add a key to a hash for a multiget query * if the hash (*value) is NULL it will be created * @param data_pool pool from where the hash and their items are created from * @param key null terminated string containing the key * @param values hash of keys and values that this key will be added to * @return */ APU_DECLARE(void) apr_memcache_add_multget_key(apr_pool_t *data_pool, const char* key, apr_hash_t **values); /** * Gets multiple values from the server, allocating the values out of p * @param mc client to use * @param temp_pool Pool used for temporary allocations. May be cleared inside this * call. * @param data_pool Pool used to allocate data for the returned values. * @param values hash of apr_memcache_value_t keyed by strings, contains the * result of the multiget call. * @return */ APU_DECLARE(apr_status_t) apr_memcache_multgetp(apr_memcache_t *mc, apr_pool_t *temp_pool, apr_pool_t *data_pool, apr_hash_t *values); /** * Sets a value by key on the server * @param mc client to use * @param key null terminated string containing the key * @param baton data to store on the server * @param data_size length of data at baton * @param timeout time in seconds for the data to live on the server * @param flags any flags set by the client for this key */ APU_DECLARE(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); /** * Adds value by key on the server * @param mc client to use * @param key null terminated string containing the key * @param baton data to store on the server * @param data_size length of data at baton * @param timeout time for the data to live on the server * @param flags any flags set by the client for this key * @return APR_SUCCESS if the key was added, APR_EEXIST if the key * already exists on the server. */ APU_DECLARE(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); /** * Replaces value by key on the server * @param mc client to use * @param key null terminated string containing the key * @param baton data to store on the server * @param data_size length of data at baton * @param timeout time for the data to live on the server * @param flags any flags set by the client for this key * @return APR_SUCCESS if the key was added, APR_EEXIST if the key * did not exist on the server. */ APU_DECLARE(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); /** * Deletes a key from a server * @param mc client to use * @param key null terminated string containing the key * @param timeout time for the delete to stop other clients from adding */ APU_DECLARE(apr_status_t) apr_memcache_delete(apr_memcache_t *mc, const char *key, apr_uint32_t timeout); /** * Increments a value * @param mc client to use * @param key null terminated string containing the key * @param n number to increment by * @param nv new value after incrementing */ APU_DECLARE(apr_status_t) apr_memcache_incr(apr_memcache_t *mc, const char *key, apr_int32_t n, apr_uint32_t *nv); /** * Decrements a value * @param mc client to use * @param key null terminated string containing the key * @param n number to decrement by * @param new_value new value after decrementing */ APU_DECLARE(apr_status_t) apr_memcache_decr(apr_memcache_t *mc, const char *key, apr_int32_t n, apr_uint32_t *new_value); /** * Query a server's version * @param ms server to query * @param p Pool to allocate answer from * @param baton location to store server version string * @param len length of the server version string */ APU_DECLARE(apr_status_t) apr_memcache_version(apr_memcache_server_t *ms, apr_pool_t *p, char **baton); typedef struct { /** Version string of this server */ const char *version; /** Process id of this server process */ apr_uint32_t pid; /** Number of seconds this server has been running */ apr_uint32_t uptime; /** current UNIX time according to the server */ apr_time_t time; /** The size of a pointer on the current machine */ apr_uint32_t pointer_size; /** Accumulated user time for this process */ apr_time_t rusage_user; /** Accumulated system time for this process */ apr_time_t rusage_system; /** Current number of items stored by the server */ apr_uint32_t curr_items; /** Total number of items stored by this server */ apr_uint32_t total_items; /** Current number of bytes used by this server to store items */ apr_uint64_t bytes; /** Number of open connections */ apr_uint32_t curr_connections; /** Total number of connections opened since the server started running */ apr_uint32_t total_connections; /** Number of connection structures allocated by the server */ apr_uint32_t connection_structures; /** Cumulative number of retrieval requests */ apr_uint32_t cmd_get; /** Cumulative number of storage requests */ apr_uint32_t cmd_set; /** Number of keys that have been requested and found present */ apr_uint32_t get_hits; /** Number of items that have been requested and not found */ apr_uint32_t get_misses; /** Number of items removed from cache because they passed their expiration time */ apr_uint64_t evictions; /** Total number of bytes read by this server */ apr_uint64_t bytes_read; /** Total number of bytes sent by this server */ apr_uint64_t bytes_written; /** Number of bytes this server is allowed to use for storage. */ apr_uint32_t limit_maxbytes; /** Number of threads the server is running (if built with threading) */ apr_uint32_t threads; } apr_memcache_stats_t; /** * Query a server for statistics * @param ms server to query * @param p Pool to allocate answer from * @param stats location of the new statistics structure */ APU_DECLARE(apr_status_t) apr_memcache_stats(apr_memcache_server_t *ms, apr_pool_t *p, apr_memcache_stats_t **stats); /** @} */ #ifdef __cplusplus } #endif #endif /* APR_MEMCACHE_H */