svn_object_pool.h revision 299742 
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
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
64
65/* The opaque object container type. */
66typedef 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 */
75typedef 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 */
83typedef 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 */
101svn_error_t *
102svn_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 */
110apr_pool_t *
111svn_object_pool__new_wrapper_pool(svn_object_pool__t *object_pool);
112
113/* Return the mutex used to serialize all OBJECT_POOL access.
114 */
115svn_mutex__t *
116svn_object_pool__mutex(svn_object_pool__t *object_pool);
117
118/* Return the number of object instances (used or unused) in OBJECT_POOL.
119 */
120unsigned
121svn_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 */
128svn_error_t *
129svn_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 */
145svn_error_t *
146svn_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 */
155