diff options
Diffstat (limited to 'subversion/include/private/svn_object_pool.h')
| -rw-r--r-- | subversion/include/private/svn_object_pool.h | 154 |
1 files changed, 154 insertions, 0 deletions
diff --git a/subversion/include/private/svn_object_pool.h b/subversion/include/private/svn_object_pool.h new file mode 100644 index 0000000..7a9383e --- /dev/null +++ b/subversion/include/private/svn_object_pool.h @@ -0,0 +1,154 @@ +/** + * @copyright + * ==================================================================== + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + * ==================================================================== + * @endcopyright + * + * @file svn_object_pool.h + * @brief multithreaded object pool API + * + * This is the core data structure behind various object pools. It + * provides a thread-safe associative container for object instances of + * the same type. + * + * Memory and lifetime management for the objects are handled by the pool. + * Reference counting takes care that neither objects nor the object pool + * get actually destroyed while other parts depend on them. All objects + * are thought to be recycle-able and live in their own root memory pools + * making them (potentially) safe to be used from different threads. + * Currently unused objects may be kept around for a while and returned + * by the next lookup. + * + * Two modes are supported: shared use and exclusive use. In shared mode, + * any object can be handed out to multiple users and in potentially + * different threads at the same time. In exclusive mode, the same object + * will only be referenced at most once. + * + * Object creation and access must be provided outside this structure. + * In particular, the using container will usually wrap the actual object + * in a meta-data struct containing key information etc and must provide + * getters and setters for those wrapper structs. + */ + + + +#ifndef SVN_OBJECT_POOL_H +#define SVN_OBJECT_POOL_H + +#include <apr.h> /* for apr_int64_t */ +#include <apr_pools.h> /* for apr_pool_t */ +#include <apr_hash.h> /* for apr_hash_t */ + +#include "svn_types.h" + +#include "private/svn_mutex.h" +#include "private/svn_string_private.h" + + + +/* The opaque object container type. */ +typedef struct svn_object_pool__t svn_object_pool__t; + +/* Extract the actual object from the WRAPPER using optional information + * from BATON (provided through #svn_object_pool__lookup) and return it. + * The result will be used with POOL and must remain valid throughout + * POOL's lifetime. + * + * It is legal to return a copy, allocated in POOL, of the wrapped object. + */ +typedef void * (* svn_object_pool__getter_t)(void *wrapper, + void *baton, + apr_pool_t *pool); + +/* Copy the information from the SOURCE object wrapper into the already + * existing *TARGET object wrapper using POOL for allocations and BATON + * for optional context (provided through #svn_object_pool__insert). + */ +typedef svn_error_t * (* svn_object_pool__setter_t)(void **target, + void *source, + void *baton, + apr_pool_t *pool); + +/* Create a new object pool in POOL and return it in *OBJECT_POOL. + * Objects will be extracted using GETTER and updated using SETTER. Either + * one (or both) may be NULL and the default implementation assumes that + * wrapper == object and updating is a no-op. + * + * If THREAD_SAFE is not set, neither the object pool nor the object + * references returned from it may be accessed from multiple threads. + * + * It is not legal to call any API on the object pool after POOL got + * cleared or destroyed. However, existing object references handed out + * from the object pool remain valid and will keep the internal pool data + * structures alive for as long as such object references exist. + */ +svn_error_t * +svn_object_pool__create(svn_object_pool__t **object_pool, + svn_object_pool__getter_t getter, + svn_object_pool__setter_t setter, + svn_boolean_t thread_safe, + apr_pool_t *pool); + +/* Return the root pool containing the OBJECT_POOL and all sub-structures. + */ +apr_pool_t * +svn_object_pool__new_wrapper_pool(svn_object_pool__t *object_pool); + +/* Return the mutex used to serialize all OBJECT_POOL access. + */ +svn_mutex__t * +svn_object_pool__mutex(svn_object_pool__t *object_pool); + +/* Return the number of object instances (used or unused) in OBJECT_POOL. + */ +unsigned +svn_object_pool__count(svn_object_pool__t *object_pool); + +/* In OBJECT_POOL, look for an available object by KEY and return a + * reference to it in *OBJECT. If none can be found, *OBJECT will be NULL. + * BATON will be passed to OBJECT_POOL's getter function. The reference + * will be returned when *RESULT_POOL gets cleaned up or destroyed. + */ +svn_error_t * +svn_object_pool__lookup(void **object, + svn_object_pool__t *object_pool, + svn_membuf_t *key, + void *baton, + apr_pool_t *result_pool); + +/* Store the wrapped object WRAPPER under KEY in OBJECT_POOL and return + * a reference to the object in *OBJECT (just like lookup). + * + * The object must have been created in WRAPPER_POOL and the latter must + * be a sub-pool of OBJECT_POOL's root POOL (see #svn_object_pool__pool). + * + * BATON will be passed to OBJECT_POOL's setter and getter functions. + * The reference will be returned when *RESULT_POOL gets cleaned up or + * destroyed. + */ +svn_error_t * +svn_object_pool__insert(void **object, + svn_object_pool__t *object_pool, + const svn_membuf_t *key, + void *wrapper, + void *baton, + apr_pool_t *wrapper_pool, + apr_pool_t *result_pool); + +#endif /* SVN_OBJECT_POOL_H */ |