/* 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 */