2 * object_pool.c : generic pool of reference-counted objects
4 * ====================================================================
5 * Licensed to the Apache Software Foundation (ASF) under one
6 * or more contributor license agreements. See the NOTICE file
7 * distributed with this work for additional information
8 * regarding copyright ownership. The ASF licenses this file
9 * to you under the Apache License, Version 2.0 (the
10 * "License"); you may not use this file except in compliance
11 * with the License. You may obtain a copy of the License at
13 * http://www.apache.org/licenses/LICENSE-2.0
15 * Unless required by applicable law or agreed to in writing,
16 * software distributed under the License is distributed on an
17 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
18 * KIND, either express or implied. See the License for the
19 * specific language governing permissions and limitations
21 * ====================================================================
29 #include "svn_error.h"
31 #include "svn_pools.h"
33 #include "private/svn_atomic.h"
34 #include "private/svn_object_pool.h"
35 #include "private/svn_subr_private.h"
36 #include "private/svn_dep_compat.h"
40 /* A reference counting wrapper around the user-provided object.
42 typedef struct object_ref_t
44 /* reference to the parent container */
45 svn_object_pool__t *object_pool;
47 /* identifies the bucket in OBJECT_POOL->OBJECTS in which this entry
51 /* User provided object. Usually a wrapper. */
54 /* private pool. This instance and its other members got allocated in it.
55 * Will be destroyed when this instance is cleaned up. */
58 /* Number of references to this data struct */
59 volatile svn_atomic_t ref_count;
63 /* Core data structure. All access to it must be serialized using MUTEX.
65 struct svn_object_pool__t
67 /* serialization object for all non-atomic data in this struct */
70 /* object_ref_t.KEY -> object_ref_t* mapping.
72 * In shared object mode, there is at most one such entry per key and it
73 * may or may not be in use. In exclusive mode, only unused references
74 * will be put here and they form chains if there are multiple unused
75 * instances for the key. */
78 /* same as objects->count but allows for non-sync'ed access */
79 volatile svn_atomic_t object_count;
81 /* Number of entries in OBJECTS with a reference count 0.
82 Due to races, this may be *temporarily* off by one or more.
83 Hence we must not strictly depend on it. */
84 volatile svn_atomic_t unused_count;
86 /* the root pool owning this structure */
91 /* Pool cleanup function for the whole object pool.
94 object_pool_cleanup(void *baton)
96 svn_object_pool__t *object_pool = baton;
98 /* all entries must have been released up by now */
99 SVN_ERR_ASSERT_NO_RETURN( object_pool->object_count
100 == object_pool->unused_count);
105 /* Remove entries from OBJECTS in OBJECT_POOL that have a ref-count of 0.
107 * Requires external serialization on OBJECT_POOL.
110 remove_unused_objects(svn_object_pool__t *object_pool)
112 apr_pool_t *subpool = svn_pool_create(object_pool->pool);
114 /* process all hash buckets */
115 apr_hash_index_t *hi;
116 for (hi = apr_hash_first(subpool, object_pool->objects);
118 hi = apr_hash_next(hi))
120 object_ref_t *object_ref = apr_hash_this_val(hi);
122 /* note that we won't hand out new references while access
123 to the hash is serialized */
124 if (svn_atomic_read(&object_ref->ref_count) == 0)
126 apr_hash_set(object_pool->objects, object_ref->key.data,
127 object_ref->key.size, NULL);
128 svn_atomic_dec(&object_pool->object_count);
129 svn_atomic_dec(&object_pool->unused_count);
131 svn_pool_destroy(object_ref->pool);
135 svn_pool_destroy(subpool);
138 /* Cleanup function called when an object_ref_t gets released.
141 object_ref_cleanup(void *baton)
143 object_ref_t *object = baton;
144 svn_object_pool__t *object_pool = object->object_pool;
146 /* If we released the last reference to object, there is one more
149 Note that unused_count does not need to be always exact but only
150 needs to become exact *eventually* (we use it to check whether we
151 should remove unused objects every now and then). I.e. it must
152 never drift off / get stuck but always reflect the true value once
153 all threads left the racy sections.
155 if (svn_atomic_dec(&object->ref_count) == 0)
156 svn_atomic_inc(&object_pool->unused_count);
161 /* Handle reference counting for the OBJECT_REF that the caller is about
162 * to return. The reference will be released when POOL gets cleaned up.
164 * Requires external serialization on OBJECT_REF->OBJECT_POOL.
167 add_object_ref(object_ref_t *object_ref,
170 /* Update ref counter.
171 Note that this is racy with object_ref_cleanup; see comment there. */
172 if (svn_atomic_inc(&object_ref->ref_count) == 0)
173 svn_atomic_dec(&object_ref->object_pool->unused_count);
175 /* Make sure the reference gets released automatically.
176 Since POOL might be a parent pool of OBJECT_REF->OBJECT_POOL,
177 to the reference counting update before destroing any of the
179 apr_pool_pre_cleanup_register(pool, object_ref, object_ref_cleanup);
182 /* Actual implementation of svn_object_pool__lookup.
184 * Requires external serialization on OBJECT_POOL.
187 lookup(void **object,
188 svn_object_pool__t *object_pool,
190 apr_pool_t *result_pool)
192 object_ref_t *object_ref
193 = apr_hash_get(object_pool->objects, key->data, key->size);
197 *object = object_ref->object;
198 add_object_ref(object_ref, result_pool);
208 /* Actual implementation of svn_object_pool__insert.
210 * Requires external serialization on OBJECT_POOL.
213 insert(void **object,
214 svn_object_pool__t *object_pool,
215 const svn_membuf_t *key,
217 apr_pool_t *item_pool,
218 apr_pool_t *result_pool)
220 object_ref_t *object_ref
221 = apr_hash_get(object_pool->objects, key->data, key->size);
224 /* Destroy the new one and return a reference to the existing one
225 * because the existing one may already have references on it.
227 svn_pool_destroy(item_pool);
231 /* add new index entry */
232 object_ref = apr_pcalloc(item_pool, sizeof(*object_ref));
233 object_ref->object_pool = object_pool;
234 object_ref->object = item;
235 object_ref->pool = item_pool;
237 svn_membuf__create(&object_ref->key, key->size, item_pool);
238 object_ref->key.size = key->size;
239 memcpy(object_ref->key.data, key->data, key->size);
241 apr_hash_set(object_pool->objects, object_ref->key.data,
242 object_ref->key.size, object_ref);
243 svn_atomic_inc(&object_pool->object_count);
245 /* the new entry is *not* in use yet.
246 * add_object_ref will update counters again.
248 svn_atomic_inc(&object_ref->object_pool->unused_count);
251 /* return a reference to the object we just added */
252 *object = object_ref->object;
253 add_object_ref(object_ref, result_pool);
255 /* limit memory usage */
256 if (svn_atomic_read(&object_pool->unused_count) * 2
257 > apr_hash_count(object_pool->objects) + 2)
258 remove_unused_objects(object_pool);
264 /* API implementation */
267 svn_object_pool__create(svn_object_pool__t **object_pool,
268 svn_boolean_t thread_safe,
271 svn_object_pool__t *result;
273 /* construct the object pool in our private ROOT_POOL to survive POOL
274 * cleanup and to prevent threading issues with the allocator
276 result = apr_pcalloc(pool, sizeof(*result));
277 SVN_ERR(svn_mutex__init(&result->mutex, thread_safe, pool));
280 result->objects = svn_hash__make(result->pool);
282 /* make sure we clean up nicely.
283 * We need two cleanup functions of which exactly one will be run
284 * (disabling the respective other as the first step). If the owning
285 * pool does not cleaned up / destroyed explicitly, it may live longer
286 * than our allocator. So, we need do act upon cleanup requests from
287 * either side - owning_pool and root_pool.
289 apr_pool_cleanup_register(pool, result, object_pool_cleanup,
290 apr_pool_cleanup_null);
292 *object_pool = result;
297 svn_object_pool__new_item_pool(svn_object_pool__t *object_pool)
299 return svn_pool_create(object_pool->pool);
303 svn_object_pool__lookup(void **object,
304 svn_object_pool__t *object_pool,
306 apr_pool_t *result_pool)
309 SVN_MUTEX__WITH_LOCK(object_pool->mutex,
310 lookup(object, object_pool, key, result_pool));
315 svn_object_pool__insert(void **object,
316 svn_object_pool__t *object_pool,
317 const svn_membuf_t *key,
319 apr_pool_t *item_pool,
320 apr_pool_t *result_pool)
323 SVN_MUTEX__WITH_LOCK(object_pool->mutex,
324 insert(object, object_pool, key, item,
325 item_pool, result_pool));