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
12
* http://www.apache.org/licenses/LICENSE-2.0
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
20
* ====================================================================
23
* @file svn_object_pool.h
24
* @brief multithreaded object pool API
26
* This is the core data structure behind various object pools. It
27
* provides a thread-safe associative container for object instances of
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
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.
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.
51
#ifndef SVN_OBJECT_POOL_H
52
#define SVN_OBJECT_POOL_H
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 */
58
#include "svn_types.h"
60
#include "private/svn_mutex.h"
61
#include "private/svn_string_private.h"
65
/* The opaque object container type. */
66
typedef struct svn_object_pool__t svn_object_pool__t;
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
73
* It is legal to return a copy, allocated in POOL, of the wrapped object.
75
typedef void * (* svn_object_pool__getter_t)(void *wrapper,
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).
83
typedef svn_error_t * (* svn_object_pool__setter_t)(void **target,
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.
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.
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.
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,
108
/* Return the root pool containing the OBJECT_POOL and all sub-structures.
111
svn_object_pool__new_wrapper_pool(svn_object_pool__t *object_pool);
113
/* Return the mutex used to serialize all OBJECT_POOL access.
116
svn_object_pool__mutex(svn_object_pool__t *object_pool);
118
/* Return the number of object instances (used or unused) in OBJECT_POOL.
121
svn_object_pool__count(svn_object_pool__t *object_pool);
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.
129
svn_object_pool__lookup(void **object,
130
svn_object_pool__t *object_pool,
133
apr_pool_t *result_pool);
135
/* Store the wrapped object WRAPPER under KEY in OBJECT_POOL and return
136
* a reference to the object in *OBJECT (just like lookup).
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).
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
146
svn_object_pool__insert(void **object,
147
svn_object_pool__t *object_pool,
148
const svn_membuf_t *key,
151
apr_pool_t *wrapper_pool,
152
apr_pool_t *result_pool);
154
#endif /* SVN_OBJECT_POOL_H */
added
removed
subversion/include/private/svn_object_pool.h
