Import apr_memcache trunk to APR-Util.

Still TODO:
- Move CRC32 to a separate public function/API.
- Create a multi-get interface.
- Make locking and connection pooling optional.


git-svn-id: http://svn.apache.org/repos/asf/apr/apr-util/trunk@329089 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 366 insertions, 0 deletions

diff --git a/include/apr_memcache.h b/include/apr_memcache.h
new file mode 100644
index 00000000..af8ba4bc
--- /dev/null
+++ b/include/apr_memcache.h
@@ -0,0 +1,366 @@
+/* Copyright 2005 The Apache Software Foundation or its licensors, as
+ * applicable.
+ *
+ * Copyright 2004-2005 Paul Querna
+ *
+ * Licensed 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"
+
+#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 */
+    apr_thread_mutex_t *lock;
+    apr_time_t btime;
+};
+
+/** Container for a set of memcached servers */
+typedef struct
+{
+    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 */
+} apr_memcache_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.
+ */
+APR_DECLARE(apr_uint32_t)
+apr_memcache_hash(const char *data, apr_uint32_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
+ */
+APR_DECLARE(apr_memcache_server_t *)
+apr_memcache_find_server_hash(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.
+ */
+APR_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.
+ */
+APR_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
+ */
+APR_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
+ */
+APR_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
+ */
+APR_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
+ */
+APR_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 
+ */
+APR_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);
+
+/**
+ * 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 len   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
+ */
+APR_DECLARE(apr_status_t) 
+apr_memcache_set(apr_memcache_t *mc,
+                 const char *key,
+                 char *baton,
+                 const apr_uint32_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 len   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.
+ */
+APR_DECLARE(apr_status_t) 
+apr_memcache_add(apr_memcache_t *mc,
+                 const char *key,
+                 char *baton,
+                 const apr_uint32_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 len   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.
+ */
+APR_DECLARE(apr_status_t) 
+apr_memcache_replace(apr_memcache_t *mc,
+                 const char *key,
+                 char *data,
+                 const apr_uint32_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
+ */
+APR_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 incrmenting
+ */
+APR_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 nv    new value after decrementing
+ */
+APR_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
+ */
+APR_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;
+    /** 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;
+    /** 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;
+} 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
+ */
+APR_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 */