contrib/subversion/subversion/include/private/svn_object_pool.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_object_pool.h
  24  * @brief multithreaded object pool API
  25  *
  26  * This is the core data structure behind various object pools.  It
  27  * provides a thread-safe associative container for object instances of
  28  * the same type.
  29  *
  30  * Memory and lifetime management for the objects are handled by the pool.
  31  * Reference counting takes care that neither objects nor the object pool
  32  * get actually destroyed while other parts depend on them.  All objects
  33  * are thought to be recycle-able and live in their own root memory pools
  34  * making them (potentially) safe to be used from different threads.
  35  * Currently unused objects may be kept around for a while and returned
  36  * by the next lookup.
  37  *
  38  * Two modes are supported: shared use and exclusive use.  In shared mode,
  39  * any object can be handed out to multiple users and in potentially
  40  * different threads at the same time.  In exclusive mode, the same object
  41  * will only be referenced at most once.
  42  *
  43  * Object creation and access must be provided outside this structure.
  44  * In particular, the using container will usually wrap the actual object
  45  * in a meta-data struct containing key information etc and must provide
  46  * getters and setters for those wrapper structs.
  47  */
  48
  49 \f
  50
  51 #ifndef SVN_OBJECT_POOL_H
  52 #define SVN_OBJECT_POOL_H
  53
  54 #include <apr.h>        /* for apr_int64_t */
  55 #include <apr_pools.h>  /* for apr_pool_t */
  56 #include <apr_hash.h>   /* for apr_hash_t */
  57
  58 #include "svn_types.h"
  59
  60 #include "private/svn_mutex.h"
  61 #include "private/svn_string_private.h"
  62
  63 \f
  64
  65 /* The opaque object container type. */
  66 typedef struct svn_object_pool__t svn_object_pool__t;
  67
  68 /* Extract the actual object from the WRAPPER using optional information
  69  * from BATON (provided through #svn_object_pool__lookup) and return it.
  70  * The result will be used with POOL and must remain valid throughout
  71  * POOL's lifetime.
  72  *
  73  * It is legal to return a copy, allocated in POOL, of the wrapped object.
  74  */
  75 typedef void * (* svn_object_pool__getter_t)(void *wrapper,
  76                                              void *baton,
  77                                              apr_pool_t *pool);
  78
  79 /* Copy the information from the SOURCE object wrapper into the already
  80  * existing *TARGET object wrapper using POOL for allocations and BATON
  81  * for optional context (provided through #svn_object_pool__insert).
  82  */
  83 typedef svn_error_t * (* svn_object_pool__setter_t)(void **target,
  84                                                     void *source,
  85                                                     void *baton,
  86                                                     apr_pool_t *pool);
  87
  88 /* Create a new object pool in POOL and return it in *OBJECT_POOL.
  89  * Objects will be extracted using GETTER and updated using SETTER.  Either
  90  * one (or both) may be NULL and the default implementation assumes that
  91  * wrapper == object and updating is a no-op.
  92  *
  93  * If THREAD_SAFE is not set, neither the object pool nor the object
  94  * references returned from it may be accessed from multiple threads.
  95  *
  96  * It is not legal to call any API on the object pool after POOL got
  97  * cleared or destroyed.  However, existing object references handed out
  98  * from the object pool remain valid and will keep the internal pool data
  99  * structures alive for as long as such object references exist.
 100  */
 101 svn_error_t *
 102 svn_object_pool__create(svn_object_pool__t **object_pool,
 103                         svn_object_pool__getter_t getter,
 104                         svn_object_pool__setter_t setter,
 105                         svn_boolean_t thread_safe,
 106                         apr_pool_t *pool);
 107
 108 /* Return the root pool containing the OBJECT_POOL and all sub-structures.
 109  */
 110 apr_pool_t *
 111 svn_object_pool__new_wrapper_pool(svn_object_pool__t *object_pool);
 112
 113 /* Return the mutex used to serialize all OBJECT_POOL access.
 114  */
 115 svn_mutex__t *
 116 svn_object_pool__mutex(svn_object_pool__t *object_pool);
 117
 118 /* Return the number of object instances (used or unused) in OBJECT_POOL.
 119  */
 120 unsigned
 121 svn_object_pool__count(svn_object_pool__t *object_pool);
 122
 123 /* In OBJECT_POOL, look for an available object by KEY and return a
 124  * reference to it in *OBJECT.  If none can be found, *OBJECT will be NULL.
 125  * BATON will be passed to OBJECT_POOL's getter function.  The reference
 126  * will be returned when *RESULT_POOL gets cleaned up or destroyed.
 127  */
 128 svn_error_t *
 129 svn_object_pool__lookup(void **object,
 130                         svn_object_pool__t *object_pool,
 131                         svn_membuf_t *key,
 132                         void *baton,
 133                         apr_pool_t *result_pool);
 134
 135 /* Store the wrapped object WRAPPER under KEY in OBJECT_POOL and return
 136  * a reference to the object in *OBJECT (just like lookup).
 137  *
 138  * The object must have been created in WRAPPER_POOL and the latter must
 139  * be a sub-pool of OBJECT_POOL's root POOL (see #svn_object_pool__pool).
 140  *
 141  * BATON will be passed to OBJECT_POOL's setter and getter functions.
 142  * The reference will be returned when *RESULT_POOL gets cleaned up or
 143  * destroyed.
 144  */
 145 svn_error_t *
 146 svn_object_pool__insert(void **object,
 147                         svn_object_pool__t *object_pool,
 148                         const svn_membuf_t *key,
 149                         void *wrapper,
 150                         void *baton,
 151                         apr_pool_t *wrapper_pool,
 152                         apr_pool_t *result_pool);
 153
 154 #endif /* SVN_OBJECT_POOL_H */