Apache Portable Runtime
|
00001 /* Licensed to the Apache Software Foundation (ASF) under one or more 00002 * contributor license agreements. See the NOTICE file distributed with 00003 * this work for additional information regarding copyright ownership. 00004 * The ASF licenses this file to You under the Apache License, Version 2.0 00005 * (the "License"); you may not use this file except in compliance with 00006 * the License. You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 00017 #ifndef APR_MEMCACHE_H 00018 #define APR_MEMCACHE_H 00019 00020 /** 00021 * @file apr_memcache.h 00022 * @brief Client interface for memcached 00023 * @remark To use this interface you must have a separate memcached 00024 * server running. See the memcached website at http://www.danga.com/memcached/ 00025 * for more information. 00026 */ 00027 00028 #include "apr.h" 00029 #include "apr_pools.h" 00030 #include "apr_time.h" 00031 #include "apr_strings.h" 00032 #include "apr_network_io.h" 00033 #include "apr_ring.h" 00034 #include "apr_buckets.h" 00035 #include "apr_reslist.h" 00036 #include "apr_hash.h" 00037 00038 #ifdef __cplusplus 00039 extern "C" { 00040 #endif /* __cplusplus */ 00041 00042 /** 00043 * @defgroup APR_Util_MC Memcached Client Routines 00044 * @ingroup APR_Util 00045 * @{ 00046 */ 00047 00048 /** Specifies the status of a memcached server */ 00049 typedef enum 00050 { 00051 APR_MC_SERVER_LIVE, /**< Server is alive and responding to requests */ 00052 APR_MC_SERVER_DEAD /**< Server is not responding to requests */ 00053 } apr_memcache_server_status_t; 00054 00055 /** Opaque memcache client connection object */ 00056 typedef struct apr_memcache_conn_t apr_memcache_conn_t; 00057 00058 /** Memcache Server Info Object */ 00059 typedef struct apr_memcache_server_t apr_memcache_server_t; 00060 struct apr_memcache_server_t 00061 { 00062 const char *host; /**< Hostname of this Server */ 00063 apr_port_t port; /**< Port of this Server */ 00064 apr_memcache_server_status_t status; /**< @see apr_memcache_server_status_t */ 00065 #if APR_HAS_THREADS || defined(DOXYGEN) 00066 apr_reslist_t *conns; /**< Resource list of actual client connections */ 00067 #else 00068 apr_memcache_conn_t *conn; 00069 #endif 00070 apr_pool_t *p; /** Pool to use for private allocations */ 00071 #if APR_HAS_THREADS 00072 apr_thread_mutex_t *lock; 00073 #endif 00074 apr_time_t btime; 00075 }; 00076 00077 /* Custom hash callback function prototype, user for server selection. 00078 * @param baton user selected baton 00079 * @param data data to hash 00080 * @param data_len length of data 00081 */ 00082 typedef apr_uint32_t (*apr_memcache_hash_func)(void *baton, 00083 const char *data, 00084 const apr_size_t data_len); 00085 00086 typedef struct apr_memcache_t apr_memcache_t; 00087 00088 /* Custom Server Select callback function prototype. 00089 * @param baton user selected baton 00090 * @param mc memcache instance, use mc->live_servers to select a node 00091 * @param hash hash of the selected key. 00092 */ 00093 typedef apr_memcache_server_t* (*apr_memcache_server_func)(void *baton, 00094 apr_memcache_t *mc, 00095 const apr_uint32_t hash); 00096 00097 /** Container for a set of memcached servers */ 00098 struct apr_memcache_t 00099 { 00100 apr_uint32_t flags; /**< Flags, Not currently used */ 00101 apr_uint16_t nalloc; /**< Number of Servers Allocated */ 00102 apr_uint16_t ntotal; /**< Number of Servers Added */ 00103 apr_memcache_server_t **live_servers; /**< Array of Servers */ 00104 apr_pool_t *p; /** Pool to use for allocations */ 00105 void *hash_baton; 00106 apr_memcache_hash_func hash_func; 00107 void *server_baton; 00108 apr_memcache_server_func server_func; 00109 }; 00110 00111 /** Returned Data from a multiple get */ 00112 typedef struct 00113 { 00114 apr_status_t status; 00115 const char* key; 00116 apr_size_t len; 00117 char *data; 00118 apr_uint16_t flags; 00119 } apr_memcache_value_t; 00120 00121 /** 00122 * Creates a crc32 hash used to split keys between servers 00123 * @param mc The memcache client object to use 00124 * @param data Data to be hashed 00125 * @param data_len Length of the data to use 00126 * @return crc32 hash of data 00127 * @remark The crc32 hash is not compatible with old memcached clients. 00128 */ 00129 APU_DECLARE(apr_uint32_t) apr_memcache_hash(apr_memcache_t *mc, 00130 const char *data, 00131 const apr_size_t data_len); 00132 00133 /** 00134 * Pure CRC32 Hash. Used by some clients. 00135 */ 00136 APU_DECLARE(apr_uint32_t) apr_memcache_hash_crc32(void *baton, 00137 const char *data, 00138 const apr_size_t data_len); 00139 00140 /** 00141 * hash compatible with the standard Perl Client. 00142 */ 00143 APU_DECLARE(apr_uint32_t) apr_memcache_hash_default(void *baton, 00144 const char *data, 00145 const apr_size_t data_len); 00146 00147 /** 00148 * Picks a server based on a hash 00149 * @param mc The memcache client object to use 00150 * @param hash Hashed value of a Key 00151 * @return server that controls specified hash 00152 * @see apr_memcache_hash 00153 */ 00154 APU_DECLARE(apr_memcache_server_t *) apr_memcache_find_server_hash(apr_memcache_t *mc, 00155 const apr_uint32_t hash); 00156 00157 /** 00158 * server selection compatible with the standard Perl Client. 00159 */ 00160 APU_DECLARE(apr_memcache_server_t *) apr_memcache_find_server_hash_default(void *baton, 00161 apr_memcache_t *mc, 00162 const apr_uint32_t hash); 00163 00164 /** 00165 * Adds a server to a client object 00166 * @param mc The memcache client object to use 00167 * @param server Server to add 00168 * @remark Adding servers is not thread safe, and should be done once at startup. 00169 * @warning Changing servers after startup may cause keys to go to 00170 * different servers. 00171 */ 00172 APU_DECLARE(apr_status_t) apr_memcache_add_server(apr_memcache_t *mc, 00173 apr_memcache_server_t *server); 00174 00175 00176 /** 00177 * Finds a Server object based on a hostname/port pair 00178 * @param mc The memcache client object to use 00179 * @param host Hostname of the server 00180 * @param port Port of the server 00181 * @return Server with matching Hostname and Port, or NULL if none was found. 00182 */ 00183 APU_DECLARE(apr_memcache_server_t *) apr_memcache_find_server(apr_memcache_t *mc, 00184 const char *host, 00185 apr_port_t port); 00186 00187 /** 00188 * Enables a Server for use again 00189 * @param mc The memcache client object to use 00190 * @param ms Server to Activate 00191 */ 00192 APU_DECLARE(apr_status_t) apr_memcache_enable_server(apr_memcache_t *mc, 00193 apr_memcache_server_t *ms); 00194 00195 00196 /** 00197 * Disable a Server 00198 * @param mc The memcache client object to use 00199 * @param ms Server to Disable 00200 */ 00201 APU_DECLARE(apr_status_t) apr_memcache_disable_server(apr_memcache_t *mc, 00202 apr_memcache_server_t *ms); 00203 00204 /** 00205 * Creates a new Server Object 00206 * @param p Pool to use 00207 * @param host hostname of the server 00208 * @param port port of the server 00209 * @param min minimum number of client sockets to open 00210 * @param smax soft maximum number of client connections to open 00211 * @param max hard maximum number of client connections 00212 * @param ttl time to live in microseconds of a client connection 00213 * @param ns location of the new server object 00214 * @see apr_reslist_create 00215 * @remark min, smax, and max are only used when APR_HAS_THREADS 00216 */ 00217 APU_DECLARE(apr_status_t) apr_memcache_server_create(apr_pool_t *p, 00218 const char *host, 00219 apr_port_t port, 00220 apr_uint32_t min, 00221 apr_uint32_t smax, 00222 apr_uint32_t max, 00223 apr_uint32_t ttl, 00224 apr_memcache_server_t **ns); 00225 /** 00226 * Creates a new memcached client object 00227 * @param p Pool to use 00228 * @param max_servers maximum number of servers 00229 * @param flags Not currently used 00230 * @param mc location of the new memcache client object 00231 */ 00232 APU_DECLARE(apr_status_t) apr_memcache_create(apr_pool_t *p, 00233 apr_uint16_t max_servers, 00234 apr_uint32_t flags, 00235 apr_memcache_t **mc); 00236 00237 /** 00238 * Gets a value from the server, allocating the value out of p 00239 * @param mc client to use 00240 * @param p Pool to use 00241 * @param key null terminated string containing the key 00242 * @param baton location of the allocated value 00243 * @param len length of data at baton 00244 * @param flags any flags set by the client for this key 00245 * @return 00246 */ 00247 APU_DECLARE(apr_status_t) apr_memcache_getp(apr_memcache_t *mc, 00248 apr_pool_t *p, 00249 const char* key, 00250 char **baton, 00251 apr_size_t *len, 00252 apr_uint16_t *flags); 00253 00254 00255 /** 00256 * Add a key to a hash for a multiget query 00257 * if the hash (*value) is NULL it will be created 00258 * @param data_pool pool from where the hash and their items are created from 00259 * @param key null terminated string containing the key 00260 * @param values hash of keys and values that this key will be added to 00261 * @return 00262 */ 00263 APU_DECLARE(void) apr_memcache_add_multget_key(apr_pool_t *data_pool, 00264 const char* key, 00265 apr_hash_t **values); 00266 00267 /** 00268 * Gets multiple values from the server, allocating the values out of p 00269 * @param mc client to use 00270 * @param temp_pool Pool used for temporary allocations. May be cleared inside this 00271 * call. 00272 * @param data_pool Pool used to allocate data for the returned values. 00273 * @param values hash of apr_memcache_value_t keyed by strings, contains the 00274 * result of the multiget call. 00275 * @return 00276 */ 00277 APU_DECLARE(apr_status_t) apr_memcache_multgetp(apr_memcache_t *mc, 00278 apr_pool_t *temp_pool, 00279 apr_pool_t *data_pool, 00280 apr_hash_t *values); 00281 00282 /** 00283 * Sets a value by key on the server 00284 * @param mc client to use 00285 * @param key null terminated string containing the key 00286 * @param baton data to store on the server 00287 * @param data_size length of data at baton 00288 * @param timeout time in seconds for the data to live on the server 00289 * @param flags any flags set by the client for this key 00290 * @bug timeout is not implemented 00291 * @bug timeouts for apr must be prototyped in apr_interval_time_t; 00292 * this changes in 2.0 00293 */ 00294 APU_DECLARE(apr_status_t) apr_memcache_set(apr_memcache_t *mc, 00295 const char *key, 00296 char *baton, 00297 const apr_size_t data_size, 00298 apr_uint32_t timeout, 00299 apr_uint16_t flags); 00300 00301 /** 00302 * Adds value by key on the server 00303 * @param mc client to use 00304 * @param key null terminated string containing the key 00305 * @param baton data to store on the server 00306 * @param data_size length of data at baton 00307 * @param timeout time for the data to live on the server 00308 * @param flags any flags set by the client for this key 00309 * @return APR_SUCCESS if the key was added, APR_EEXIST if the key 00310 * already exists on the server. 00311 */ 00312 APU_DECLARE(apr_status_t) apr_memcache_add(apr_memcache_t *mc, 00313 const char *key, 00314 char *baton, 00315 const apr_size_t data_size, 00316 apr_uint32_t timeout, 00317 apr_uint16_t flags); 00318 00319 /** 00320 * Replaces value by key on the server 00321 * @param mc client to use 00322 * @param key null terminated string containing the key 00323 * @param baton data to store on the server 00324 * @param data_size length of data at baton 00325 * @param timeout time for the data to live on the server 00326 * @param flags any flags set by the client for this key 00327 * @return APR_SUCCESS if the key was added, APR_EEXIST if the key 00328 * did not exist on the server. 00329 */ 00330 APU_DECLARE(apr_status_t) apr_memcache_replace(apr_memcache_t *mc, 00331 const char *key, 00332 char *baton, 00333 const apr_size_t data_size, 00334 apr_uint32_t timeout, 00335 apr_uint16_t flags); 00336 /** 00337 * Deletes a key from a server 00338 * @param mc client to use 00339 * @param key null terminated string containing the key 00340 * @param timeout time for the delete to stop other clients from adding 00341 */ 00342 APU_DECLARE(apr_status_t) apr_memcache_delete(apr_memcache_t *mc, 00343 const char *key, 00344 apr_uint32_t timeout); 00345 00346 /** 00347 * Increments a value 00348 * @param mc client to use 00349 * @param key null terminated string containing the key 00350 * @param n number to increment by 00351 * @param nv new value after incrementing 00352 */ 00353 APU_DECLARE(apr_status_t) apr_memcache_incr(apr_memcache_t *mc, 00354 const char *key, 00355 apr_int32_t n, 00356 apr_uint32_t *nv); 00357 00358 /** 00359 * Decrements a value 00360 * @param mc client to use 00361 * @param key null terminated string containing the key 00362 * @param n number to decrement by 00363 * @param new_value new value after decrementing 00364 */ 00365 APU_DECLARE(apr_status_t) apr_memcache_decr(apr_memcache_t *mc, 00366 const char *key, 00367 apr_int32_t n, 00368 apr_uint32_t *new_value); 00369 00370 /** 00371 * Query a server's version 00372 * @param ms server to query 00373 * @param p Pool to allocate answer from 00374 * @param baton location to store server version string 00375 * @param len length of the server version string 00376 */ 00377 APU_DECLARE(apr_status_t) apr_memcache_version(apr_memcache_server_t *ms, 00378 apr_pool_t *p, 00379 char **baton); 00380 00381 typedef struct 00382 { 00383 /** Version string of this server */ 00384 const char *version; 00385 /** Process id of this server process */ 00386 apr_uint32_t pid; 00387 /** Number of seconds this server has been running */ 00388 apr_uint32_t uptime; 00389 /** current UNIX time according to the server */ 00390 apr_time_t time; 00391 /** The size of a pointer on the current machine */ 00392 apr_uint32_t pointer_size; 00393 /** Accumulated user time for this process */ 00394 apr_time_t rusage_user; 00395 /** Accumulated system time for this process */ 00396 apr_time_t rusage_system; 00397 /** Current number of items stored by the server */ 00398 apr_uint32_t curr_items; 00399 /** Total number of items stored by this server */ 00400 apr_uint32_t total_items; 00401 /** Current number of bytes used by this server to store items */ 00402 apr_uint64_t bytes; 00403 /** Number of open connections */ 00404 apr_uint32_t curr_connections; 00405 /** Total number of connections opened since the server started running */ 00406 apr_uint32_t total_connections; 00407 /** Number of connection structures allocated by the server */ 00408 apr_uint32_t connection_structures; 00409 /** Cumulative number of retrieval requests */ 00410 apr_uint32_t cmd_get; 00411 /** Cumulative number of storage requests */ 00412 apr_uint32_t cmd_set; 00413 /** Number of keys that have been requested and found present */ 00414 apr_uint32_t get_hits; 00415 /** Number of items that have been requested and not found */ 00416 apr_uint32_t get_misses; 00417 /** Number of items removed from cache because they passed their 00418 expiration time */ 00419 apr_uint64_t evictions; 00420 /** Total number of bytes read by this server */ 00421 apr_uint64_t bytes_read; 00422 /** Total number of bytes sent by this server */ 00423 apr_uint64_t bytes_written; 00424 /** Number of bytes this server is allowed to use for storage. */ 00425 apr_uint32_t limit_maxbytes; 00426 /** Number of threads the server is running (if built with threading) */ 00427 apr_uint32_t threads; 00428 } apr_memcache_stats_t; 00429 00430 /** 00431 * Query a server for statistics 00432 * @param ms server to query 00433 * @param p Pool to allocate answer from 00434 * @param stats location of the new statistics structure 00435 */ 00436 APU_DECLARE(apr_status_t) apr_memcache_stats(apr_memcache_server_t *ms, 00437 apr_pool_t *p, 00438 apr_memcache_stats_t **stats); 00439 00440 00441 /** @} */ 00442 00443 #ifdef __cplusplus 00444 } 00445 #endif 00446 00447 #endif /* APR_MEMCACHE_H */