445 lines
17 KiB
C
445 lines
17 KiB
C
|
/* 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 */
|