contrib/subversion/subversion/include/private/svn_cache.h

   1 /**
   2  * @copyright
   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
  11  *
  12  *      http://www.apache.org/licenses/LICENSE-2.0
  13  *
  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
  19  *    under the License.
  20  * ====================================================================
  21  * @endcopyright
  22  *
  23  * @file svn_cache.h
  24  * @brief In-memory cache implementation.
  25  */
  26
  27
  28 #ifndef SVN_CACHE_H
  29 #define SVN_CACHE_H
  30
  31 #include <apr_pools.h>
  32 #include <apr_hash.h>
  33
  34 #include "svn_types.h"
  35 #include "svn_error.h"
  36 #include "svn_iter.h"
  37 #include "svn_config.h"
  38 #include "svn_string.h"
  39
  40 #ifdef __cplusplus
  41 extern "C" {
  42 #endif /* __cplusplus */
  43
  44 \f
  45
  46 /**
  47  * @defgroup svn_cache__support In-memory caching
  48  * @{
  49  */
  50
  51 /**
  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.
  56  */
  57 typedef svn_error_t *(*svn_cache__deserialize_func_t)(void **out,
  58                                                       void *data,
  59                                                       apr_size_t data_len,
  60                                                       apr_pool_t *result_pool);
  61
  62 /**
  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.
  68  */
  69 typedef svn_error_t *(*svn_cache__partial_getter_func_t)(void **out,
  70                                                          const void *data,
  71                                                          apr_size_t data_len,
  72                                                          void *baton,
  73                                                          apr_pool_t *result_pool);
  74
  75 /**
  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.
  82  */
  83 typedef svn_error_t *(*svn_cache__partial_setter_func_t)(void **data,
  84                                                          apr_size_t *data_len,
  85                                                          void *baton,
  86                                                          apr_pool_t *result_pool);
  87
  88 /**
  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.
  92  */
  93 typedef svn_error_t *(*svn_cache__serialize_func_t)(void **data,
  94                                                     apr_size_t *data_len,
  95                                                     void *in,
  96                                                     apr_pool_t *result_pool);
  97
  98 /**
  99  * A function type for transforming or ignoring errors.  @a scratch_pool may
 100  * be used for temporary allocations.
 101  */
 102 typedef svn_error_t *(*svn_cache__error_handler_t)(svn_error_t *err,
 103                                                    void *baton,
 104                                                    apr_pool_t *scratch_pool);
 105
 106 /**
 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.
 110  */
 111 typedef struct svn_memcache_t svn_memcache_t;
 112
 113 /**
 114  * An opaque structure representing a membuffer cache object.
 115  */
 116 typedef struct svn_membuffer_t svn_membuffer_t;
 117
 118 /**
 119  * Opaque type for an in-memory cache.
 120  */
 121 typedef struct svn_cache__t svn_cache__t;
 122
 123 /**
 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.
 127  */
 128 typedef struct svn_cache__info_t
 129 {
 130   /** A string identifying the cache instance. Usually a copy of the @a id
 131    * or @a prefix parameter passed to the cache constructor.
 132    */
 133   const char* id;
 134
 135   /** Number of getter calls (svn_cache__get() or svn_cache__get()).
 136    */
 137   apr_uint64_t gets;
 138
 139   /** Number of getter calls that return data.
 140    */
 141   apr_uint64_t hits;
 142
 143   /** Number of setter calls (svn_cache__set()).
 144    */
 145   apr_uint64_t sets;
 146
 147   /** Number of function calls that returned an error.
 148    */
 149   apr_uint64_t failures;
 150
 151   /** Size of the data currently stored in the cache.
 152    * May be 0 if that information is not available.
 153    */
 154   apr_uint64_t used_size;
 155
 156   /** Amount of memory currently reserved for cached data.
 157    * Will be equal to @a used_size if no precise information is available.
 158    */
 159   apr_uint64_t data_size;
 160
 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.
 164    */
 165   apr_uint64_t total_size;
 166
 167   /** Number of cache entries.
 168    * May be 0 if that information is not available.
 169    */
 170   apr_uint64_t used_entries;
 171
 172   /** Maximum numbers of cache entries.
 173    * May be 0 if that information is not available.
 174    */
 175   apr_uint64_t total_entries;
 176 } svn_cache__info_t;
 177
 178 /**
 179  * Creates a new cache in @a *cache_p.  This cache will use @a pool
 180  * for all of its storage needs.  The elements in the cache will be
 181  * indexed by keys of length @a klen, which may be APR_HASH_KEY_STRING
 182  * if they are strings.  Cached values will be copied in and out of
 183  * the cache using @a serialize_func and @a deserialize_func, respectively.
 184  *
 185  * If @a deserialize_func is NULL, then the data is returned as an
 186  * svn_stringbuf_t; if @a serialize_func is NULL, then the data is
 187  * assumed to be an svn_stringbuf_t.
 188  *
 189  * The cache stores up to @a pages * @a items_per_page items at a
 190  * time.  The exact cache invalidation strategy is not defined here,
 191  * but in general, a lower value for @a items_per_page means more
 192  * memory overhead for the same number of items, but a higher value
 193  * for @a items_per_page means more items are cleared at once.  Both
 194  * @a pages and @a items_per_page must be positive (though they both
 195  * may certainly be 1).
 196  *
 197  * If @a thread_safe is true, and APR is compiled with threads, all
 198  * accesses to the cache will be protected with a mutex. The @a id
 199  * is a purely user-visible information that will allow coders to
 200  * identify this cache instance in a #svn_cache__info_t struct.
 201  * It does not influence the behavior of the cache itself.
 202  *
 203  * Note that NULL is a legitimate value for cache entries (and
 204  * @a serialize_func will not be called on it).
 205  *
 206  * It is not safe for @a serialize_func nor @a deserialize_func to
 207  * interact with the cache itself.
 208  */
 209 svn_error_t *
 210 svn_cache__create_inprocess(svn_cache__t **cache_p,
 211                             svn_cache__serialize_func_t serialize_func,
 212                             svn_cache__deserialize_func_t deserialize_func,
 213                             apr_ssize_t klen,
 214                             apr_int64_t pages,
 215                             apr_int64_t items_per_page,
 216                             svn_boolean_t thread_safe,
 217                             const char *id,
 218                             apr_pool_t *pool);
 219
 220 /**
 221  * Creates a new cache in @a *cache_p, communicating to a memcached
 222  * process via @a memcache.  The elements in the cache will be indexed
 223  * by keys of length @a klen, which may be APR_HASH_KEY_STRING if they
 224  * are strings.  Values will be serialized for memcached using @a
 225  * serialize_func and deserialized using @a deserialize_func.  Because
 226  * the same memcached server may cache many different kinds of values,
 227  * @a prefix should be specified to differentiate this cache from
 228  * other caches.  @a *cache_p will be allocated in @a result_pool.
 229  *
 230  * If @a deserialize_func is NULL, then the data is returned as an
 231  * svn_stringbuf_t; if @a serialize_func is NULL, then the data is
 232  * assumed to be an svn_stringbuf_t.
 233  *
 234  * These caches are always thread safe.
 235  *
 236  * These caches do not support svn_cache__iter.
 237  *
 238  * If Subversion was not built with apr_memcache support, always
 239  * raises SVN_ERR_NO_APR_MEMCACHE.
 240  */
 241 svn_error_t *
 242 svn_cache__create_memcache(svn_cache__t **cache_p,
 243                            svn_memcache_t *memcache,
 244                            svn_cache__serialize_func_t serialize_func,
 245                            svn_cache__deserialize_func_t deserialize_func,
 246                            apr_ssize_t klen,
 247                            const char *prefix,
 248                            apr_pool_t *result_pool);
 249
 250 /**
 251  * Given @a config, returns an APR memcached interface in @a
 252  * *memcache_p allocated in @a result_pool if @a config contains entries in
 253  * the SVN_CACHE_CONFIG_CATEGORY_MEMCACHED_SERVERS section describing
 254  * memcached servers; otherwise, sets @a *memcache_p to NULL.
 255  *
 256  * If Subversion was not built with apr_memcache_support, then raises
 257  * SVN_ERR_NO_APR_MEMCACHE if and only if @a config is configured to
 258  * use memcache.
 259  */
 260 svn_error_t *
 261 svn_cache__make_memcache_from_config(svn_memcache_t **memcache_p,
 262                                      svn_config_t *config,
 263                                      apr_pool_t *result_pool);
 264
 265 /**
 266  * Creates a new membuffer cache object in @a *cache. It will contain
 267  * up to @a total_size bytes of data, using @a directory_size bytes
 268  * for index information and the remainder for serialized objects.
 269  *
 270  * Since each index entry is about 50 bytes long, 1 to 10 percent of
 271  * the @a total_size should be allocated to the @a directory_size,
 272  * depending on the average serialized object size. Higher percentages
 273  * will generally result in higher hit rates and reduced conflict
 274  * resolution overhead.
 275  *
 276  * The cache will be split into @a segment_count segments of equal size.
 277  * A higher number reduces lock contention but also limits the maximum
 278  * cachable item size.  If it is not a power of two, it will be rounded
 279  * down to next lower power of two. Also, there is an implementation
 280  * specific upper limit and the setting will be capped there automatically.
 281  * If the number is 0, a default will be derived from @a total_size.
 282  *
 283  * If access to the resulting cache object is guaranteed to be serialized,
 284  * @a thread_safe may be set to @c FALSE for maximum performance.
 285  *
 286  * There is no limit on the number of threads reading a given cache segment
 287  * concurrently.  Writes, however, need an exclusive lock on the respective
 288  * segment.  @a allow_blocking_writes controls contention is handled here.
 289  * If set to TRUE, writes will wait until the lock becomes available, i.e.
 290  * reads should be short.  If set to FALSE, write attempts will be ignored
 291  * (no data being written to the cache) if some reader or another writer
 292  * currently holds the segment lock.
 293  *
 294  * Allocations will be made in @a result_pool, in particular the data buffers.
 295  */
 296 svn_error_t *
 297 svn_cache__membuffer_cache_create(svn_membuffer_t **cache,
 298                                   apr_size_t total_size,
 299                                   apr_size_t directory_size,
 300                                   apr_size_t segment_count,
 301                                   svn_boolean_t thread_safe,
 302                                   svn_boolean_t allow_blocking_writes,
 303                                   apr_pool_t *result_pool);
 304
 305 /**
 306  * Creates a new cache in @a *cache_p, storing the data in a potentially
 307  * shared @a membuffer object.  The elements in the cache will be indexed
 308  * by keys of length @a klen, which may be APR_HASH_KEY_STRING if they
 309  * are strings.  Values will be serialized for the memcache using @a
 310  * serialize_func and deserialized using @a deserialize_func.  Because
 311  * the same memcache object may cache many different kinds of values
 312  * form multiple caches, @a prefix should be specified to differentiate
 313  * this cache from other caches.  @a *cache_p will be allocated in @a result_pool.
 314  *
 315  * If @a deserialize_func is NULL, then the data is returned as an
 316  * svn_stringbuf_t; if @a serialize_func is NULL, then the data is
 317  * assumed to be an svn_stringbuf_t.
 318  *
 319  * If @a thread_safe is true, and APR is compiled with threads, all
 320  * accesses to the cache will be protected with a mutex, if the shared
 321  * @a memcache has also been created with thread_safe flag set.
 322  *
 323  * These caches do not support svn_cache__iter.
 324  */
 325 svn_error_t *
 326 svn_cache__create_membuffer_cache(svn_cache__t **cache_p,
 327                                   svn_membuffer_t *membuffer,
 328                                   svn_cache__serialize_func_t serialize,
 329                                   svn_cache__deserialize_func_t deserialize,
 330                                   apr_ssize_t klen,
 331                                   const char *prefix,
 332                                   svn_boolean_t thread_safe,
 333                                   apr_pool_t *result_pool);
 334
 335 /**
 336  * Sets @a handler to be @a cache's error handling routine.  If any
 337  * error is returned from a call to svn_cache__get or svn_cache__set, @a
 338  * handler will be called with @a baton and the error, and the
 339  * original function will return whatever error @a handler returns
 340  * instead (possibly SVN_NO_ERROR); @a handler will receive the pool
 341  * passed to the svn_cache_* function.  @a scratch_pool is used for temporary
 342  * allocations.
 343  */
 344 svn_error_t *
 345 svn_cache__set_error_handler(svn_cache__t *cache,
 346                              svn_cache__error_handler_t handler,
 347                              void *baton,
 348                              apr_pool_t *scratch_pool);
 349
 350 /**
 351  * Returns @c TRUE if the @a cache supports objects of the given @a size.
 352  * There is no guarantee, that svn_cache__set() will actually store the
 353  * respective object in that case. However, a @c FALSE return value indicates
 354  * that an attempt to cache the item will either fail or impair the overall
 355  * cache performance. @c FALSE will also be returned if @a cache is @c NULL.
 356  */
 357 svn_boolean_t
 358 svn_cache__is_cachable(svn_cache__t *cache,
 359                        apr_size_t size);
 360
 361 #define SVN_CACHE_CONFIG_CATEGORY_MEMCACHED_SERVERS "memcached-servers"
 362
 363 /**
 364  * Fetches a value indexed by @a key from @a cache into @a *value,
 365  * setting @a *found to TRUE iff it is in the cache and FALSE if it is
 366  * not found.  @a key may be NULL in which case @a *found will be
 367  * FALSE.  The value is copied into @a result_pool using the deserialize
 368  * function provided to the cache's constructor.
 369  */
 370 svn_error_t *
 371 svn_cache__get(void **value,
 372                svn_boolean_t *found,
 373                svn_cache__t *cache,
 374                const void *key,
 375                apr_pool_t *result_pool);
 376
 377 /**
 378  * Stores the value @a value under the key @a key in @a cache.  Uses @a
 379  * scratch_pool for temporary allocations.  The cache makes copies of
 380  * @a key and @a value if necessary (that is, @a key and @a value may
 381  * have shorter lifetimes than the cache).  @a key may be NULL in which
 382  * case the cache will remain unchanged.
 383  *
 384  * If there is already a value for @a key, this will replace it.  Bear
 385  * in mind that in some circumstances this may leak memory (that is,
 386  * the cache's copy of the previous value may not be immediately
 387  * cleared); it is only guaranteed to not leak for caches created with
 388  * @a items_per_page equal to 1.
 389  */
 390 svn_error_t *
 391 svn_cache__set(svn_cache__t *cache,
 392                const void *key,
 393                void *value,
 394                apr_pool_t *scratch_pool);
 395
 396 /**
 397  * Iterates over the elements currently in @a cache, calling @a func
 398  * for each one until there are no more elements or @a func returns an
 399  * error.  Uses @a scratch_pool for temporary allocations.
 400  *
 401  * If @a completed is not NULL, then on return - if @a func returns no
 402  * errors - @a *completed will be set to @c TRUE.
 403  *
 404  * If @a func returns an error other than @c SVN_ERR_ITER_BREAK, that
 405  * error is returned.  When @a func returns @c SVN_ERR_ITER_BREAK,
 406  * iteration is interrupted, but no error is returned and @a
 407  * *completed is set to @c FALSE.  (The error handler set by
 408  * svn_cache__set_error_handler is not used for svn_cache__iter.)
 409  *
 410  * It is not legal to perform any other cache operations on @a cache
 411  * inside @a func.
 412  *
 413  * svn_cache__iter is not supported by all cache implementations; see
 414  * the svn_cache__create_* function for details.
 415  */
 416 svn_error_t *
 417 svn_cache__iter(svn_boolean_t *completed,
 418                 svn_cache__t *cache,
 419                 svn_iter_apr_hash_cb_t func,
 420                 void *baton,
 421                 apr_pool_t *scratch_pool);
 422
 423 /**
 424  * Similar to svn_cache__get() but will call a specific de-serialization
 425  * function @a func. @a found will be set depending on whether the @a key
 426  * has been found. Even if that reports @c TRUE, @a value may still return
 427  * a @c NULL pointer depending on the logic inside @a func.  For a @a NULL
 428  * @a key, no data will be found.  @a value will be allocated in
 429  * @a result_pool.
 430  */
 431 svn_error_t *
 432 svn_cache__get_partial(void **value,
 433                        svn_boolean_t *found,
 434                        svn_cache__t *cache,
 435                        const void *key,
 436                        svn_cache__partial_getter_func_t func,
 437                        void *baton,
 438                        apr_pool_t *result_pool);
 439
 440 /**
 441  * Find the item identified by @a key in the @a cache. If it has been found,
 442  * call @a func for it and @a baton to potentially modify the data. Changed
 443  * data will be written back to the cache. If the item cannot be found,
 444  * or if @a key is NULL, @a func does not get called. @a scratch_pool is
 445  * used for temporary allocations.
 446  */
 447 svn_error_t *
 448 svn_cache__set_partial(svn_cache__t *cache,
 449                        const void *key,
 450                        svn_cache__partial_setter_func_t func,
 451                        void *baton,
 452                        apr_pool_t *scratch_pool);
 453
 454 /**
 455  * Collect all available usage statistics on the cache instance @a cache
 456  * and write the data into @a info. If @a reset has been set, access
 457  * counters will be reset right after copying the statistics info.
 458  * @a result_pool will be used for allocations.
 459  */
 460 svn_error_t *
 461 svn_cache__get_info(svn_cache__t *cache,
 462                     svn_cache__info_t *info,
 463                     svn_boolean_t reset,
 464                     apr_pool_t *result_pool);
 465
 466 /**
 467  * Return the information given in @a info formatted as a multi-line string.
 468  * Allocations take place in @a result_pool.
 469  */
 470 svn_string_t *
 471 svn_cache__format_info(const svn_cache__info_t *info,
 472                        apr_pool_t *result_pool);
 473
 474 /* Access the process-global (singleton) membuffer cache. The first call
 475  * will automatically allocate the cache using the current cache config.
 476  * NULL will be returned if the desired cache size is 0.
 477  *
 478  * @since New in 1.7.
 479  */
 480 struct svn_membuffer_t *
 481 svn_cache__get_global_membuffer_cache(void);
 482
 483 /** @} */
 484
 485
 486 #ifdef __cplusplus
 487 }
 488 #endif /* __cplusplus */
 489
 490 #endif /* SVN_CACHE_H */