| /** |
| * @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; |
| |
| /* Create a new object pool in POOL and return it in *OBJECT_POOL. |
| * Objects are reference-counted and stored as opaque pointers. Each |
| * must be allocated in a separate pool ceated by |
| * svn_object_pool__new_item_pool. Unused objects get destroyed at |
| * the object pool's discretion. |
| * |
| * 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 nor to use any objects from this object pool. |
| */ |
| svn_error_t * |
| svn_object_pool__create(svn_object_pool__t **object_pool, |
| svn_boolean_t thread_safe, |
| apr_pool_t *pool); |
| |
| /* Return a pool to allocate the new object. |
| */ |
| apr_pool_t * |
| svn_object_pool__new_item_pool(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. |
| * |
| * The reference will be returned when *RESULT_POOL and may be destroyed |
| * or recycled by OBJECT_POOL. |
| */ |
| svn_error_t * |
| svn_object_pool__lookup(void **object, |
| svn_object_pool__t *object_pool, |
| svn_membuf_t *key, |
| apr_pool_t *result_pool); |
| |
| /* Store the object ITEM under KEY in OBJECT_POOL and return a reference |
| * to the object in *OBJECT (just like lookup). |
| * |
| * The object must have been created in ITEM_POOL and the latter must |
| * have been created by svn_object_pool__new_item_pool. |
| * |
| * 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 *item, |
| apr_pool_t *item_pool, |
| apr_pool_t *result_pool); |
| |
| #endif /* SVN_OBJECT_POOL_H */ |