apr_memcache.h

Apache官方在今天放出产品系列2.2的最新版本2.2.11的源码包 最流行的HTTP服务器软件之一

/* 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 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 ms 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 seconds 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);