diff options
Diffstat (limited to 'subversion/include/private/svn_cache.h')
-rw-r--r-- | subversion/include/private/svn_cache.h | 58 |
1 files changed, 42 insertions, 16 deletions
diff --git a/subversion/include/private/svn_cache.h b/subversion/include/private/svn_cache.h index c3a8a71..08d2f09 100644 --- a/subversion/include/private/svn_cache.h +++ b/subversion/include/private/svn_cache.h @@ -55,7 +55,7 @@ extern "C" { * i.e. modify @a data directly and return it in @a *out. */ typedef svn_error_t *(*svn_cache__deserialize_func_t)(void **out, - char *data, + void *data, apr_size_t data_len, apr_pool_t *result_pool); @@ -67,7 +67,7 @@ typedef svn_error_t *(*svn_cache__deserialize_func_t)(void **out, * not require the whole structure to be processed. */ typedef svn_error_t *(*svn_cache__partial_getter_func_t)(void **out, - const char *data, + const void *data, apr_size_t data_len, void *baton, apr_pool_t *result_pool); @@ -80,7 +80,7 @@ typedef svn_error_t *(*svn_cache__partial_getter_func_t)(void **out, * values must be passed back in @a *data_len and @a *data, respectively. * Allocations will be done from @a result_pool. */ -typedef svn_error_t *(*svn_cache__partial_setter_func_t)(char **data, +typedef svn_error_t *(*svn_cache__partial_setter_func_t)(void **data, apr_size_t *data_len, void *baton, apr_pool_t *result_pool); @@ -90,7 +90,7 @@ typedef svn_error_t *(*svn_cache__partial_setter_func_t)(char **data, * function should allocate the serialized value in @a result_pool, set * @a *data to the serialized value, and set @a *data_len to its length. */ -typedef svn_error_t *(*svn_cache__serialize_func_t)(char **data, +typedef svn_error_t *(*svn_cache__serialize_func_t)(void **data, apr_size_t *data_len, void *in, apr_pool_t *result_pool); @@ -182,6 +182,10 @@ typedef struct svn_cache__info_t * if they are strings. Cached values will be copied in and out of * the cache using @a serialize_func and @a deserialize_func, respectively. * + * If @a deserialize_func is NULL, then the data is returned as an + * svn_stringbuf_t; if @a serialize_func is NULL, then the data is + * assumed to be an svn_stringbuf_t. + * * The cache stores up to @a pages * @a items_per_page items at a * time. The exact cache invalidation strategy is not defined here, * but in general, a lower value for @a items_per_page means more @@ -224,7 +228,7 @@ svn_cache__create_inprocess(svn_cache__t **cache_p, * other caches. @a *cache_p will be allocated in @a result_pool. * * If @a deserialize_func is NULL, then the data is returned as an - * svn_string_t; if @a serialize_func is NULL, then the data is + * svn_stringbuf_t; if @a serialize_func is NULL, then the data is * assumed to be an svn_stringbuf_t. * * These caches are always thread safe. @@ -269,16 +273,33 @@ svn_cache__make_memcache_from_config(svn_memcache_t **memcache_p, * will generally result in higher hit rates and reduced conflict * resolution overhead. * - * If access to the resulting cache object is guranteed to be serialized, + * The cache will be split into @a segment_count segments of equal size. + * A higher number reduces lock contention but also limits the maximum + * cachable item size. If it is not a power of two, it will be rounded + * down to next lower power of two. Also, there is an implementation + * specific upper limit and the setting will be capped there automatically. + * If the number is 0, a default will be derived from @a total_size. + * + * If access to the resulting cache object is guaranteed to be serialized, * @a thread_safe may be set to @c FALSE for maximum performance. * + * There is no limit on the number of threads reading a given cache segment + * concurrently. Writes, however, need an exclusive lock on the respective + * segment. @a allow_blocking_writes controls contention is handled here. + * If set to TRUE, writes will wait until the lock becomes available, i.e. + * reads should be short. If set to FALSE, write attempts will be ignored + * (no data being written to the cache) if some reader or another writer + * currently holds the segment lock. + * * Allocations will be made in @a result_pool, in particular the data buffers. */ svn_error_t * svn_cache__membuffer_cache_create(svn_membuffer_t **cache, apr_size_t total_size, apr_size_t directory_size, + apr_size_t segment_count, svn_boolean_t thread_safe, + svn_boolean_t allow_blocking_writes, apr_pool_t *result_pool); /** @@ -292,11 +313,12 @@ svn_cache__membuffer_cache_create(svn_membuffer_t **cache, * this cache from other caches. @a *cache_p will be allocated in @a result_pool. * * If @a deserialize_func is NULL, then the data is returned as an - * svn_string_t; if @a serialize_func is NULL, then the data is + * svn_stringbuf_t; if @a serialize_func is NULL, then the data is * assumed to be an svn_stringbuf_t. * - * These caches themselves are thread safe, the shared @a memcache may - * be not, depending on its creation parameters. + * If @a thread_safe is true, and APR is compiled with threads, all + * accesses to the cache will be protected with a mutex, if the shared + * @a memcache has also been created with thread_safe flag set. * * These caches do not support svn_cache__iter. */ @@ -307,6 +329,7 @@ svn_cache__create_membuffer_cache(svn_cache__t **cache_p, svn_cache__deserialize_func_t deserialize, apr_ssize_t klen, const char *prefix, + svn_boolean_t thread_safe, apr_pool_t *result_pool); /** @@ -340,9 +363,9 @@ svn_cache__is_cachable(svn_cache__t *cache, /** * Fetches a value indexed by @a key from @a cache into @a *value, * setting @a *found to TRUE iff it is in the cache and FALSE if it is - * not found. The value is copied into @a result_pool using the copy + * not found. @a key may be NULL in which case @a *found will be + * FALSE. The value is copied into @a result_pool using the deserialize * function provided to the cache's constructor. - * ### what copy function? there are serialize/deserialize functions, no copy functions */ svn_error_t * svn_cache__get(void **value, @@ -355,7 +378,8 @@ svn_cache__get(void **value, * Stores the value @a value under the key @a key in @a cache. Uses @a * scratch_pool for temporary allocations. The cache makes copies of * @a key and @a value if necessary (that is, @a key and @a value may - * have shorter lifetimes than the cache). + * have shorter lifetimes than the cache). @a key may be NULL in which + * case the cache will remain unchanged. * * If there is already a value for @a key, this will replace it. Bear * in mind that in some circumstances this may leak memory (that is, @@ -399,8 +423,10 @@ svn_cache__iter(svn_boolean_t *completed, /** * Similar to svn_cache__get() but will call a specific de-serialization * function @a func. @a found will be set depending on whether the @a key - * has been found. Even if that reports @c TRUE, @a values may still return - * a @c NULL pointer depending on the logic inside @a func. + * has been found. Even if that reports @c TRUE, @a value may still return + * a @c NULL pointer depending on the logic inside @a func. For a @a NULL + * @a key, no data will be found. @a value will be allocated in + * @a result_pool. */ svn_error_t * svn_cache__get_partial(void **value, @@ -415,8 +441,8 @@ svn_cache__get_partial(void **value, * Find the item identified by @a key in the @a cache. If it has been found, * call @a func for it and @a baton to potentially modify the data. Changed * data will be written back to the cache. If the item cannot be found, - * @a func does not get called. @a scratch_pool is used for temporary - * allocations. + * or if @a key is NULL, @a func does not get called. @a scratch_pool is + * used for temporary allocations. */ svn_error_t * svn_cache__set_partial(svn_cache__t *cache, |