Annotation of win32/apache22/srclib/apr-util/include/apr_memcache.h, revision 1.1
1.1 ! moko 1: /* Licensed to the Apache Software Foundation (ASF) under one or more
! 2: * contributor license agreements. See the NOTICE file distributed with
! 3: * this work for additional information regarding copyright ownership.
! 4: * The ASF licenses this file to You under the Apache License, Version 2.0
! 5: * (the "License"); you may not use this file except in compliance with
! 6: * the License. You may obtain a copy of the License at
! 7: *
! 8: * http://www.apache.org/licenses/LICENSE-2.0
! 9: *
! 10: * Unless required by applicable law or agreed to in writing, software
! 11: * distributed under the License is distributed on an "AS IS" BASIS,
! 12: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
! 13: * See the License for the specific language governing permissions and
! 14: * limitations under the License.
! 15: */
! 16:
! 17: #ifndef APR_MEMCACHE_H
! 18: #define APR_MEMCACHE_H
! 19:
! 20: /**
! 21: * @file apr_memcache.h
! 22: * @brief Client interface for memcached
! 23: * @remark To use this interface you must have a separate memcached
! 24: * server running. See the memcached website at http://www.danga.com/memcached/
! 25: * for more information.
! 26: */
! 27:
! 28: #include "apr.h"
! 29: #include "apr_pools.h"
! 30: #include "apr_time.h"
! 31: #include "apr_strings.h"
! 32: #include "apr_network_io.h"
! 33: #include "apr_ring.h"
! 34: #include "apr_buckets.h"
! 35: #include "apr_reslist.h"
! 36: #include "apr_hash.h"
! 37:
! 38: #ifdef __cplusplus
! 39: extern "C" {
! 40: #endif /* __cplusplus */
! 41:
! 42: /**
! 43: * @defgroup APR_Util_MC Memcached Client Routines
! 44: * @ingroup APR_Util
! 45: * @{
! 46: */
! 47:
! 48: /** Specifies the status of a memcached server */
! 49: typedef enum
! 50: {
! 51: APR_MC_SERVER_LIVE, /**< Server is alive and responding to requests */
! 52: APR_MC_SERVER_DEAD /**< Server is not responding to requests */
! 53: } apr_memcache_server_status_t;
! 54:
! 55: /** Opaque memcache client connection object */
! 56: typedef struct apr_memcache_conn_t apr_memcache_conn_t;
! 57:
! 58: /** Memcache Server Info Object */
! 59: typedef struct apr_memcache_server_t apr_memcache_server_t;
! 60: struct apr_memcache_server_t
! 61: {
! 62: const char *host; /**< Hostname of this Server */
! 63: apr_port_t port; /**< Port of this Server */
! 64: apr_memcache_server_status_t status; /**< @see apr_memcache_server_status_t */
! 65: #if APR_HAS_THREADS || defined(DOXYGEN)
! 66: apr_reslist_t *conns; /**< Resource list of actual client connections */
! 67: #else
! 68: apr_memcache_conn_t *conn;
! 69: #endif
! 70: apr_pool_t *p; /** Pool to use for private allocations */
! 71: #if APR_HAS_THREADS
! 72: apr_thread_mutex_t *lock;
! 73: #endif
! 74: apr_time_t btime;
! 75: };
! 76:
! 77: /* Custom hash callback function prototype, user for server selection.
! 78: * @param baton user selected baton
! 79: * @param data data to hash
! 80: * @param data_len length of data
! 81: */
! 82: typedef apr_uint32_t (*apr_memcache_hash_func)(void *baton,
! 83: const char *data,
! 84: const apr_size_t data_len);
! 85:
! 86: typedef struct apr_memcache_t apr_memcache_t;
! 87:
! 88: /* Custom Server Select callback function prototype.
! 89: * @param baton user selected baton
! 90: * @param mc memcache instance, use mc->live_servers to select a node
! 91: * @param hash hash of the selected key.
! 92: */
! 93: typedef apr_memcache_server_t* (*apr_memcache_server_func)(void *baton,
! 94: apr_memcache_t *mc,
! 95: const apr_uint32_t hash);
! 96:
! 97: /** Container for a set of memcached servers */
! 98: struct apr_memcache_t
! 99: {
! 100: apr_uint32_t flags; /**< Flags, Not currently used */
! 101: apr_uint16_t nalloc; /**< Number of Servers Allocated */
! 102: apr_uint16_t ntotal; /**< Number of Servers Added */
! 103: apr_memcache_server_t **live_servers; /**< Array of Servers */
! 104: apr_pool_t *p; /** Pool to use for allocations */
! 105: void *hash_baton;
! 106: apr_memcache_hash_func hash_func;
! 107: void *server_baton;
! 108: apr_memcache_server_func server_func;
! 109: };
! 110:
! 111: /** Returned Data from a multiple get */
! 112: typedef struct
! 113: {
! 114: apr_status_t status;
! 115: const char* key;
! 116: apr_size_t len;
! 117: char *data;
! 118: apr_uint16_t flags;
! 119: } apr_memcache_value_t;
! 120:
! 121: /**
! 122: * Creates a crc32 hash used to split keys between servers
! 123: * @param mc The memcache client object to use
! 124: * @param data Data to be hashed
! 125: * @param data_len Length of the data to use
! 126: * @return crc32 hash of data
! 127: * @remark The crc32 hash is not compatible with old memcached clients.
! 128: */
! 129: APU_DECLARE(apr_uint32_t) apr_memcache_hash(apr_memcache_t *mc,
! 130: const char *data,
! 131: const apr_size_t data_len);
! 132:
! 133: /**
! 134: * Pure CRC32 Hash. Used by some clients.
! 135: */
! 136: APU_DECLARE(apr_uint32_t) apr_memcache_hash_crc32(void *baton,
! 137: const char *data,
! 138: const apr_size_t data_len);
! 139:
! 140: /**
! 141: * hash compatible with the standard Perl Client.
! 142: */
! 143: APU_DECLARE(apr_uint32_t) apr_memcache_hash_default(void *baton,
! 144: const char *data,
! 145: const apr_size_t data_len);
! 146:
! 147: /**
! 148: * Picks a server based on a hash
! 149: * @param mc The memcache client object to use
! 150: * @param hash Hashed value of a Key
! 151: * @return server that controls specified hash
! 152: * @see apr_memcache_hash
! 153: */
! 154: APU_DECLARE(apr_memcache_server_t *) apr_memcache_find_server_hash(apr_memcache_t *mc,
! 155: const apr_uint32_t hash);
! 156:
! 157: /**
! 158: * server selection compatible with the standard Perl Client.
! 159: */
! 160: APU_DECLARE(apr_memcache_server_t *) apr_memcache_find_server_hash_default(void *baton,
! 161: apr_memcache_t *mc,
! 162: const apr_uint32_t hash);
! 163:
! 164: /**
! 165: * Adds a server to a client object
! 166: * @param mc The memcache client object to use
! 167: * @param server Server to add
! 168: * @remark Adding servers is not thread safe, and should be done once at startup.
! 169: * @warning Changing servers after startup may cause keys to go to
! 170: * different servers.
! 171: */
! 172: APU_DECLARE(apr_status_t) apr_memcache_add_server(apr_memcache_t *mc,
! 173: apr_memcache_server_t *server);
! 174:
! 175:
! 176: /**
! 177: * Finds a Server object based on a hostname/port pair
! 178: * @param mc The memcache client object to use
! 179: * @param host Hostname of the server
! 180: * @param port Port of the server
! 181: * @return Server with matching Hostname and Port, or NULL if none was found.
! 182: */
! 183: APU_DECLARE(apr_memcache_server_t *) apr_memcache_find_server(apr_memcache_t *mc,
! 184: const char *host,
! 185: apr_port_t port);
! 186:
! 187: /**
! 188: * Enables a Server for use again
! 189: * @param mc The memcache client object to use
! 190: * @param ms Server to Activate
! 191: */
! 192: APU_DECLARE(apr_status_t) apr_memcache_enable_server(apr_memcache_t *mc,
! 193: apr_memcache_server_t *ms);
! 194:
! 195:
! 196: /**
! 197: * Disable a Server
! 198: * @param mc The memcache client object to use
! 199: * @param ms Server to Disable
! 200: */
! 201: APU_DECLARE(apr_status_t) apr_memcache_disable_server(apr_memcache_t *mc,
! 202: apr_memcache_server_t *ms);
! 203:
! 204: /**
! 205: * Creates a new Server Object
! 206: * @param p Pool to use
! 207: * @param host hostname of the server
! 208: * @param port port of the server
! 209: * @param min minimum number of client sockets to open
! 210: * @param smax soft maximum number of client connections to open
! 211: * @param max hard maximum number of client connections
! 212: * @param ttl time to live in microseconds of a client connection
! 213: * @param ns location of the new server object
! 214: * @see apr_reslist_create
! 215: * @remark min, smax, and max are only used when APR_HAS_THREADS
! 216: */
! 217: APU_DECLARE(apr_status_t) apr_memcache_server_create(apr_pool_t *p,
! 218: const char *host,
! 219: apr_port_t port,
! 220: apr_uint32_t min,
! 221: apr_uint32_t smax,
! 222: apr_uint32_t max,
! 223: apr_uint32_t ttl,
! 224: apr_memcache_server_t **ns);
! 225: /**
! 226: * Creates a new memcached client object
! 227: * @param p Pool to use
! 228: * @param max_servers maximum number of servers
! 229: * @param flags Not currently used
! 230: * @param mc location of the new memcache client object
! 231: */
! 232: APU_DECLARE(apr_status_t) apr_memcache_create(apr_pool_t *p,
! 233: apr_uint16_t max_servers,
! 234: apr_uint32_t flags,
! 235: apr_memcache_t **mc);
! 236:
! 237: /**
! 238: * Gets a value from the server, allocating the value out of p
! 239: * @param mc client to use
! 240: * @param p Pool to use
! 241: * @param key null terminated string containing the key
! 242: * @param baton location of the allocated value
! 243: * @param len length of data at baton
! 244: * @param flags any flags set by the client for this key
! 245: * @return
! 246: */
! 247: APU_DECLARE(apr_status_t) apr_memcache_getp(apr_memcache_t *mc,
! 248: apr_pool_t *p,
! 249: const char* key,
! 250: char **baton,
! 251: apr_size_t *len,
! 252: apr_uint16_t *flags);
! 253:
! 254:
! 255: /**
! 256: * Add a key to a hash for a multiget query
! 257: * if the hash (*value) is NULL it will be created
! 258: * @param data_pool pool from where the hash and their items are created from
! 259: * @param key null terminated string containing the key
! 260: * @param values hash of keys and values that this key will be added to
! 261: * @return
! 262: */
! 263: APU_DECLARE(void) apr_memcache_add_multget_key(apr_pool_t *data_pool,
! 264: const char* key,
! 265: apr_hash_t **values);
! 266:
! 267: /**
! 268: * Gets multiple values from the server, allocating the values out of p
! 269: * @param mc client to use
! 270: * @param temp_pool Pool used for temporary allocations. May be cleared inside this
! 271: * call.
! 272: * @param data_pool Pool used to allocate data for the returned values.
! 273: * @param values hash of apr_memcache_value_t keyed by strings, contains the
! 274: * result of the multiget call.
! 275: * @return
! 276: */
! 277: APU_DECLARE(apr_status_t) apr_memcache_multgetp(apr_memcache_t *mc,
! 278: apr_pool_t *temp_pool,
! 279: apr_pool_t *data_pool,
! 280: apr_hash_t *values);
! 281:
! 282: /**
! 283: * Sets a value by key on the server
! 284: * @param mc client to use
! 285: * @param key null terminated string containing the key
! 286: * @param baton data to store on the server
! 287: * @param data_size length of data at baton
! 288: * @param timeout time in seconds for the data to live on the server
! 289: * @param flags any flags set by the client for this key
! 290: */
! 291: APU_DECLARE(apr_status_t) apr_memcache_set(apr_memcache_t *mc,
! 292: const char *key,
! 293: char *baton,
! 294: const apr_size_t data_size,
! 295: apr_uint32_t timeout,
! 296: apr_uint16_t flags);
! 297:
! 298: /**
! 299: * Adds value by key on the server
! 300: * @param mc client to use
! 301: * @param key null terminated string containing the key
! 302: * @param baton data to store on the server
! 303: * @param data_size length of data at baton
! 304: * @param timeout time for the data to live on the server
! 305: * @param flags any flags set by the client for this key
! 306: * @return APR_SUCCESS if the key was added, APR_EEXIST if the key
! 307: * already exists on the server.
! 308: */
! 309: APU_DECLARE(apr_status_t) apr_memcache_add(apr_memcache_t *mc,
! 310: const char *key,
! 311: char *baton,
! 312: const apr_size_t data_size,
! 313: apr_uint32_t timeout,
! 314: apr_uint16_t flags);
! 315:
! 316: /**
! 317: * Replaces value by key on the server
! 318: * @param mc client to use
! 319: * @param key null terminated string containing the key
! 320: * @param baton data to store on the server
! 321: * @param data_size length of data at baton
! 322: * @param timeout time for the data to live on the server
! 323: * @param flags any flags set by the client for this key
! 324: * @return APR_SUCCESS if the key was added, APR_EEXIST if the key
! 325: * did not exist on the server.
! 326: */
! 327: APU_DECLARE(apr_status_t) apr_memcache_replace(apr_memcache_t *mc,
! 328: const char *key,
! 329: char *baton,
! 330: const apr_size_t data_size,
! 331: apr_uint32_t timeout,
! 332: apr_uint16_t flags);
! 333: /**
! 334: * Deletes a key from a server
! 335: * @param mc client to use
! 336: * @param key null terminated string containing the key
! 337: * @param timeout time for the delete to stop other clients from adding
! 338: */
! 339: APU_DECLARE(apr_status_t) apr_memcache_delete(apr_memcache_t *mc,
! 340: const char *key,
! 341: apr_uint32_t timeout);
! 342:
! 343: /**
! 344: * Increments a value
! 345: * @param mc client to use
! 346: * @param key null terminated string containing the key
! 347: * @param n number to increment by
! 348: * @param nv new value after incrementing
! 349: */
! 350: APU_DECLARE(apr_status_t) apr_memcache_incr(apr_memcache_t *mc,
! 351: const char *key,
! 352: apr_int32_t n,
! 353: apr_uint32_t *nv);
! 354:
! 355: /**
! 356: * Decrements a value
! 357: * @param mc client to use
! 358: * @param key null terminated string containing the key
! 359: * @param n number to decrement by
! 360: * @param new_value new value after decrementing
! 361: */
! 362: APU_DECLARE(apr_status_t) apr_memcache_decr(apr_memcache_t *mc,
! 363: const char *key,
! 364: apr_int32_t n,
! 365: apr_uint32_t *new_value);
! 366:
! 367: /**
! 368: * Query a server's version
! 369: * @param ms server to query
! 370: * @param p Pool to allocate answer from
! 371: * @param baton location to store server version string
! 372: * @param len length of the server version string
! 373: */
! 374: APU_DECLARE(apr_status_t) apr_memcache_version(apr_memcache_server_t *ms,
! 375: apr_pool_t *p,
! 376: char **baton);
! 377:
! 378: typedef struct
! 379: {
! 380: /** Version string of this server */
! 381: const char *version;
! 382: /** Process id of this server process */
! 383: apr_uint32_t pid;
! 384: /** Number of seconds this server has been running */
! 385: apr_uint32_t uptime;
! 386: /** current UNIX time according to the server */
! 387: apr_time_t time;
! 388: /** The size of a pointer on the current machine */
! 389: apr_uint32_t pointer_size;
! 390: /** Accumulated user time for this process */
! 391: apr_time_t rusage_user;
! 392: /** Accumulated system time for this process */
! 393: apr_time_t rusage_system;
! 394: /** Current number of items stored by the server */
! 395: apr_uint32_t curr_items;
! 396: /** Total number of items stored by this server */
! 397: apr_uint32_t total_items;
! 398: /** Current number of bytes used by this server to store items */
! 399: apr_uint64_t bytes;
! 400: /** Number of open connections */
! 401: apr_uint32_t curr_connections;
! 402: /** Total number of connections opened since the server started running */
! 403: apr_uint32_t total_connections;
! 404: /** Number of connection structures allocated by the server */
! 405: apr_uint32_t connection_structures;
! 406: /** Cumulative number of retrieval requests */
! 407: apr_uint32_t cmd_get;
! 408: /** Cumulative number of storage requests */
! 409: apr_uint32_t cmd_set;
! 410: /** Number of keys that have been requested and found present */
! 411: apr_uint32_t get_hits;
! 412: /** Number of items that have been requested and not found */
! 413: apr_uint32_t get_misses;
! 414: /** Number of items removed from cache because they passed their
! 415: expiration time */
! 416: apr_uint64_t evictions;
! 417: /** Total number of bytes read by this server */
! 418: apr_uint64_t bytes_read;
! 419: /** Total number of bytes sent by this server */
! 420: apr_uint64_t bytes_written;
! 421: /** Number of bytes this server is allowed to use for storage. */
! 422: apr_uint32_t limit_maxbytes;
! 423: /** Number of threads the server is running (if built with threading) */
! 424: apr_uint32_t threads;
! 425: } apr_memcache_stats_t;
! 426:
! 427: /**
! 428: * Query a server for statistics
! 429: * @param ms server to query
! 430: * @param p Pool to allocate answer from
! 431: * @param stats location of the new statistics structure
! 432: */
! 433: APU_DECLARE(apr_status_t) apr_memcache_stats(apr_memcache_server_t *ms,
! 434: apr_pool_t *p,
! 435: apr_memcache_stats_t **stats);
! 436:
! 437:
! 438: /** @} */
! 439:
! 440: #ifdef __cplusplus
! 441: }
! 442: #endif
! 443:
! 444: #endif /* APR_MEMCACHE_H */
E-mail:
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to apr_memcache.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [parser3project] / win32 / apache22 / srclib / apr-util / include