3 * ====================================================================
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
12 * http://www.apache.org/licenses/LICENSE-2.0
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
20 * ====================================================================
24 * @brief In-memory cache implementation.
31 #include <apr_pools.h>
34 #include "svn_types.h"
35 #include "svn_error.h"
37 #include "svn_config.h"
38 #include "svn_string.h"
42 #endif /* __cplusplus */
47 * @defgroup svn_cache__support In-memory caching
52 * A function type for deserializing an object @a *out from the string
53 * @a data of length @a data_len into @a result_pool. It is legal and
54 * generally suggested that the deserialization will be done in-place,
55 * i.e. modify @a data directly and return it in @a *out.
57 typedef svn_error_t *(*svn_cache__deserialize_func_t)(void **out,
60 apr_pool_t *result_pool);
63 * A function type for deserializing an object @a *out from the string
64 * @a data of length @a data_len into @a result_pool. The extra information
65 * @a baton passed into can be used to deserialize only a specific part or
66 * sub-structure or to perform any other non-modifying operation that may
67 * not require the whole structure to be processed.
69 typedef svn_error_t *(*svn_cache__partial_getter_func_t)(void **out,
73 apr_pool_t *result_pool);
76 * A function type for modifying an already deserialized in the @a *data
77 * buffer of length @a *data_len. Additional information of the modification
78 * to do will be provided in @a baton. The function may change the size of
79 * data buffer and may re-allocate it if necessary. In that case, the new
80 * values must be passed back in @a *data_len and @a *data, respectively.
81 * Allocations will be done from @a result_pool.
83 typedef svn_error_t *(*svn_cache__partial_setter_func_t)(void **data,
86 apr_pool_t *result_pool);
89 * A function type for serializing an object @a in into bytes. The
90 * function should allocate the serialized value in @a result_pool, set
91 * @a *data to the serialized value, and set @a *data_len to its length.
93 typedef svn_error_t *(*svn_cache__serialize_func_t)(void **data,
96 apr_pool_t *result_pool);
99 * A function type for transforming or ignoring errors. @a scratch_pool may
100 * be used for temporary allocations.
102 typedef svn_error_t *(*svn_cache__error_handler_t)(svn_error_t *err,
104 apr_pool_t *scratch_pool);
107 * A wrapper around apr_memcache_t, provided essentially so that the
108 * Subversion public API doesn't depend on whether or not you have
109 * access to the APR memcache libraries.
111 typedef struct svn_memcache_t svn_memcache_t;
114 * An opaque structure representing a membuffer cache object.
116 typedef struct svn_membuffer_t svn_membuffer_t;
119 * Opaque type for an in-memory cache.
121 typedef struct svn_cache__t svn_cache__t;
124 * A structure containing typical statistics about a given cache instance.
125 * Use svn_cache__get_info() to get this data. Note that not all types
126 * of caches will be able to report complete and correct information.
128 typedef struct svn_cache__info_t
130 /** A string identifying the cache instance. Usually a copy of the @a id
131 * or @a prefix parameter passed to the cache constructor.
135 /** Number of getter calls (svn_cache__get() or svn_cache__get()).
139 /** Number of getter calls that return data.
143 /** Number of setter calls (svn_cache__set()).
147 /** Number of function calls that returned an error.
149 apr_uint64_t failures;
151 /** Size of the data currently stored in the cache.
152 * May be 0 if that information is not available.
154 apr_uint64_t used_size;
156 /** Amount of memory currently reserved for cached data.
157 * Will be equal to @a used_size if no precise information is available.
159 apr_uint64_t data_size;
161 /** Lower threshold of the total size of memory allocated to the cache and
162 * its index as well as management structures. The actual memory allocated
163 * by the cache may be larger.
165 apr_uint64_t total_size;
167 /** Number of cache entries.
168 * May be 0 if that information is not available.
170 apr_uint64_t used_entries;
172 /** Maximum numbers of cache entries.
173 * May be 0 if that information is not available.
175 apr_uint64_t total_entries;
177 /** Number of index buckets with the given number of entries.
178 * Bucket sizes larger than the array will saturate into the
179 * highest array index.
181 apr_uint64_t histogram[32];
185 * Creates a new cache in @a *cache_p. This cache will use @a pool
186 * for all of its storage needs. The elements in the cache will be
187 * indexed by keys of length @a klen, which may be APR_HASH_KEY_STRING
188 * if they are strings. Cached values will be copied in and out of
189 * the cache using @a serialize_func and @a deserialize_func, respectively.
191 * If @a deserialize_func is NULL, then the data is returned as an
192 * svn_stringbuf_t; if @a serialize_func is NULL, then the data is
193 * assumed to be an svn_stringbuf_t.
195 * The cache stores up to @a pages * @a items_per_page items at a
196 * time. The exact cache invalidation strategy is not defined here,
197 * but in general, a lower value for @a items_per_page means more
198 * memory overhead for the same number of items, but a higher value
199 * for @a items_per_page means more items are cleared at once. Both
200 * @a pages and @a items_per_page must be positive (though they both
201 * may certainly be 1).
203 * If @a thread_safe is true, and APR is compiled with threads, all
204 * accesses to the cache will be protected with a mutex. The @a id
205 * is a purely user-visible information that will allow coders to
206 * identify this cache instance in a #svn_cache__info_t struct.
207 * It does not influence the behavior of the cache itself.
209 * Note that NULL is a legitimate value for cache entries (and
210 * @a serialize_func will not be called on it).
212 * It is not safe for @a serialize_func nor @a deserialize_func to
213 * interact with the cache itself.
216 svn_cache__create_inprocess(svn_cache__t **cache_p,
217 svn_cache__serialize_func_t serialize_func,
218 svn_cache__deserialize_func_t deserialize_func,
221 apr_int64_t items_per_page,
222 svn_boolean_t thread_safe,
227 * Creates a new cache in @a *cache_p, communicating to a memcached
228 * process via @a memcache. The elements in the cache will be indexed
229 * by keys of length @a klen, which may be APR_HASH_KEY_STRING if they
230 * are strings. Values will be serialized for memcached using @a
231 * serialize_func and deserialized using @a deserialize_func. Because
232 * the same memcached server may cache many different kinds of values,
233 * @a prefix should be specified to differentiate this cache from
234 * other caches. @a *cache_p will be allocated in @a result_pool.
236 * If @a deserialize_func is NULL, then the data is returned as an
237 * svn_stringbuf_t; if @a serialize_func is NULL, then the data is
238 * assumed to be an svn_stringbuf_t.
240 * These caches are always thread safe.
242 * These caches do not support svn_cache__iter.
244 * If Subversion was not built with apr_memcache support, always
245 * raises SVN_ERR_NO_APR_MEMCACHE.
248 svn_cache__create_memcache(svn_cache__t **cache_p,
249 svn_memcache_t *memcache,
250 svn_cache__serialize_func_t serialize_func,
251 svn_cache__deserialize_func_t deserialize_func,
254 apr_pool_t *result_pool);
257 * Given @a config, returns an APR memcached interface in @a
258 * *memcache_p allocated in @a result_pool if @a config contains entries in
259 * the SVN_CACHE_CONFIG_CATEGORY_MEMCACHED_SERVERS section describing
260 * memcached servers; otherwise, sets @a *memcache_p to NULL. Use
261 * @a scratch_pool for temporary allocations.
263 * If Subversion was not built with apr_memcache_support, then raises
264 * SVN_ERR_NO_APR_MEMCACHE if and only if @a config is configured to
268 svn_cache__make_memcache_from_config(svn_memcache_t **memcache_p,
269 svn_config_t *config,
270 apr_pool_t *result_pool,
271 apr_pool_t *scratch_pool);
274 * Creates a new membuffer cache object in @a *cache. It will contain
275 * up to @a total_size bytes of data, using @a directory_size bytes
276 * for index information and the remainder for serialized objects.
278 * Since each index entry is about 50 bytes long, 1 to 10 percent of
279 * the @a total_size should be allocated to the @a directory_size,
280 * depending on the average serialized object size. Higher percentages
281 * will generally result in higher hit rates and reduced conflict
282 * resolution overhead.
284 * The cache will be split into @a segment_count segments of equal size.
285 * A higher number reduces lock contention but also limits the maximum
286 * cachable item size. If it is not a power of two, it will be rounded
287 * down to next lower power of two. Also, there is an implementation
288 * specific upper limit and the setting will be capped there automatically.
289 * If the number is 0, a default will be derived from @a total_size.
291 * If access to the resulting cache object is guaranteed to be serialized,
292 * @a thread_safe may be set to @c FALSE for maximum performance.
294 * There is no limit on the number of threads reading a given cache segment
295 * concurrently. Writes, however, need an exclusive lock on the respective
296 * segment. @a allow_blocking_writes controls contention is handled here.
297 * If set to TRUE, writes will wait until the lock becomes available, i.e.
298 * reads should be short. If set to FALSE, write attempts will be ignored
299 * (no data being written to the cache) if some reader or another writer
300 * currently holds the segment lock.
302 * Allocations will be made in @a result_pool, in particular the data buffers.
305 svn_cache__membuffer_cache_create(svn_membuffer_t **cache,
306 apr_size_t total_size,
307 apr_size_t directory_size,
308 apr_size_t segment_count,
309 svn_boolean_t thread_safe,
310 svn_boolean_t allow_blocking_writes,
311 apr_pool_t *result_pool);
314 * @defgroup Standard priority classes for #svn_cache__create_membuffer_cache.
319 * Data in this priority class should not be removed from the cache unless
320 * absolutely necessary. Use of this should be very restricted.
322 #define SVN_CACHE__MEMBUFFER_HIGH_PRIORITY 10000
325 * Data in this priority class has a good chance to remain in cache unless
326 * there is more data in this class than the cache's capacity. Use of this
327 * as the default for all information that is costly to fetch from disk.
329 #define SVN_CACHE__MEMBUFFER_DEFAULT_PRIORITY 1000
332 * Data in this priority class will be removed as soon as the cache starts
333 * filling up. Use of this for ephemeral data that can easily be acquired
334 * again from other sources.
336 #define SVN_CACHE__MEMBUFFER_LOW_PRIORITY 100
341 * Creates a new cache in @a *cache_p, storing the data in a potentially
342 * shared @a membuffer object. The elements in the cache will be indexed
343 * by keys of length @a klen, which may be APR_HASH_KEY_STRING if they
344 * are strings. Values will be serialized for the memcache using @a
345 * serialize_func and deserialized using @a deserialize_func. Because
346 * the same memcache object may cache many different kinds of values
347 * form multiple caches, @a prefix should be specified to differentiate
348 * this cache from other caches. All entries written through this cache
349 * interface will be assigned into the given @a priority class. @a *cache_p
350 * will be allocated in @a result_pool. @a scratch_pool is used for
351 * temporary allocations.
353 * If @a deserialize_func is NULL, then the data is returned as an
354 * svn_stringbuf_t; if @a serialize_func is NULL, then the data is
355 * assumed to be an svn_stringbuf_t.
357 * If @a thread_safe is true, and APR is compiled with threads, all
358 * accesses to the cache will be protected with a mutex, if the shared
359 * @a memcache has also been created with thread_safe flag set.
361 * These caches do not support svn_cache__iter.
364 svn_cache__create_membuffer_cache(svn_cache__t **cache_p,
365 svn_membuffer_t *membuffer,
366 svn_cache__serialize_func_t serialize,
367 svn_cache__deserialize_func_t deserialize,
370 apr_uint32_t priority,
371 svn_boolean_t thread_safe,
372 apr_pool_t *result_pool,
373 apr_pool_t *scratch_pool);
376 * Sets @a handler to be @a cache's error handling routine. If any
377 * error is returned from a call to svn_cache__get or svn_cache__set, @a
378 * handler will be called with @a baton and the error, and the
379 * original function will return whatever error @a handler returns
380 * instead (possibly SVN_NO_ERROR); @a handler will receive the pool
381 * passed to the svn_cache_* function. @a scratch_pool is used for temporary
385 svn_cache__set_error_handler(svn_cache__t *cache,
386 svn_cache__error_handler_t handler,
388 apr_pool_t *scratch_pool);
391 * Returns @c TRUE if the @a cache supports objects of the given @a size.
392 * There is no guarantee, that svn_cache__set() will actually store the
393 * respective object in that case. However, a @c FALSE return value indicates
394 * that an attempt to cache the item will either fail or impair the overall
395 * cache performance. @c FALSE will also be returned if @a cache is @c NULL.
398 svn_cache__is_cachable(svn_cache__t *cache,
401 #define SVN_CACHE_CONFIG_CATEGORY_MEMCACHED_SERVERS "memcached-servers"
404 * Fetches a value indexed by @a key from @a cache into @a *value,
405 * setting @a *found to TRUE iff it is in the cache and FALSE if it is
406 * not found. @a key may be NULL in which case @a *found will be
407 * FALSE. The value is copied into @a result_pool using the deserialize
408 * function provided to the cache's constructor.
411 svn_cache__get(void **value,
412 svn_boolean_t *found,
415 apr_pool_t *result_pool);
418 * Looks for an entry indexed by @a key in @a cache, setting @a *found
419 * to TRUE if an entry has been found and FALSE otherwise. @a key may be
420 * NULL in which case @a *found will be FALSE. Temporary allocations will
421 * be made from @a scratch_pool.
424 svn_cache__has_key(svn_boolean_t *found,
427 apr_pool_t *scratch_pool);
430 * Stores the value @a value under the key @a key in @a cache. Uses @a
431 * scratch_pool for temporary allocations. The cache makes copies of
432 * @a key and @a value if necessary (that is, @a key and @a value may
433 * have shorter lifetimes than the cache). @a key may be NULL in which
434 * case the cache will remain unchanged.
436 * If there is already a value for @a key, this will replace it. Bear
437 * in mind that in some circumstances this may leak memory (that is,
438 * the cache's copy of the previous value may not be immediately
439 * cleared); it is only guaranteed to not leak for caches created with
440 * @a items_per_page equal to 1.
443 svn_cache__set(svn_cache__t *cache,
446 apr_pool_t *scratch_pool);
449 * Iterates over the elements currently in @a cache, calling @a func
450 * for each one until there are no more elements or @a func returns an
451 * error. Uses @a scratch_pool for temporary allocations.
453 * If @a completed is not NULL, then on return - if @a func returns no
454 * errors - @a *completed will be set to @c TRUE.
456 * If @a func returns an error other than @c SVN_ERR_ITER_BREAK, that
457 * error is returned. When @a func returns @c SVN_ERR_ITER_BREAK,
458 * iteration is interrupted, but no error is returned and @a
459 * *completed is set to @c FALSE. (The error handler set by
460 * svn_cache__set_error_handler is not used for svn_cache__iter.)
462 * It is not legal to perform any other cache operations on @a cache
465 * svn_cache__iter is not supported by all cache implementations; see
466 * the svn_cache__create_* function for details.
469 svn_cache__iter(svn_boolean_t *completed,
471 svn_iter_apr_hash_cb_t func,
473 apr_pool_t *scratch_pool);
476 * Similar to svn_cache__get() but will call a specific de-serialization
477 * function @a func. @a found will be set depending on whether the @a key
478 * has been found. Even if that reports @c TRUE, @a value may still return
479 * a @c NULL pointer depending on the logic inside @a func. For a @a NULL
480 * @a key, no data will be found. @a value will be allocated in
484 svn_cache__get_partial(void **value,
485 svn_boolean_t *found,
488 svn_cache__partial_getter_func_t func,
490 apr_pool_t *result_pool);
493 * Find the item identified by @a key in the @a cache. If it has been found,
494 * call @a func for it and @a baton to potentially modify the data. Changed
495 * data will be written back to the cache. If the item cannot be found,
496 * or if @a key is NULL, @a func does not get called. @a scratch_pool is
497 * used for temporary allocations.
500 svn_cache__set_partial(svn_cache__t *cache,
502 svn_cache__partial_setter_func_t func,
504 apr_pool_t *scratch_pool);
507 * Collect all available usage statistics on the cache instance @a cache
508 * and write the data into @a info. If @a reset has been set, access
509 * counters will be reset right after copying the statistics info.
510 * @a result_pool will be used for allocations.
513 svn_cache__get_info(svn_cache__t *cache,
514 svn_cache__info_t *info,
516 apr_pool_t *result_pool);
519 * Return the information given in @a info formatted as a multi-line string.
520 * If @a access_only has been set, size and fill-level statistics will be
521 * omitted. Allocations take place in @a result_pool.
524 svn_cache__format_info(const svn_cache__info_t *info,
525 svn_boolean_t access_only,
526 apr_pool_t *result_pool);
529 * Access the process-global (singleton) membuffer cache. The first call
530 * will automatically allocate the cache using the current cache config.
531 * NULL will be returned if the desired cache size is 0.
535 struct svn_membuffer_t *
536 svn_cache__get_global_membuffer_cache(void);
539 * Return total access and size stats over all membuffer caches as they
540 * share the underlying data buffer. The result will be allocated in POOL.
543 svn_cache__membuffer_get_global_info(apr_pool_t *pool);
546 * Remove all current contents from CACHE.
548 * NOTE: In a multi-threaded environment, new contents may have been put
549 * into the cache by the time this function returns.
552 svn_cache__membuffer_clear(svn_membuffer_t *cache);
559 #endif /* __cplusplus */
561 #endif /* SVN_CACHE_H */