Subversion
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
svn_pools.h
Go to the documentation of this file.
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_pools.h
24  * @brief APR pool management for Subversion
25  */
26 
27 
28 
29 
30 #ifndef SVN_POOLS_H
31 #define SVN_POOLS_H
32 
33 #include "svn_types.h"
34 
35 #ifdef __cplusplus
36 extern "C" {
37 #endif /* __cplusplus */
38 
39 
40 
41 /* Wrappers around APR pools, so we get debugging. */
42 
43 /** The recommended maximum amount of memory (4MB) to keep in an APR
44  * allocator on the free list, conveniently defined here to share
45  * between all our applications.
46  */
47 #define SVN_ALLOCATOR_RECOMMENDED_MAX_FREE (4096 * 1024)
48 
49 
50 /** Wrapper around apr_pool_create_ex(), with a simpler interface.
51  * The return pool will have an abort function set, which will call
52  * abort() on OOM.
53  */
54 apr_pool_t *
55 svn_pool_create_ex(apr_pool_t *parent_pool,
56  apr_allocator_t *allocator);
57 
58 #ifndef DOXYGEN_SHOULD_SKIP_THIS
59 apr_pool_t *
60 svn_pool_create_ex_debug(apr_pool_t *parent_pool,
61  apr_allocator_t *allocator,
62  const char *file_line);
63 
64 #if APR_POOL_DEBUG
65 #define svn_pool_create_ex(pool, allocator) \
66 svn_pool_create_ex_debug(pool, allocator, APR_POOL__FILE_LINE__)
67 
68 #endif /* APR_POOL_DEBUG */
69 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
70 
71 
72 /** Create a pool as a subpool of @a parent_pool */
73 #define svn_pool_create(parent_pool) svn_pool_create_ex(parent_pool, NULL)
74 
75 /** Clear a @a pool destroying its children.
76  *
77  * This define for @c svn_pool_clear exists for completeness.
78  */
79 #define svn_pool_clear apr_pool_clear
80 
81 
82 /** Destroy a @a pool and all of its children.
83  *
84  * This define for @c svn_pool_destroy exists for symmetry and
85  * completeness.
86  */
87 #define svn_pool_destroy apr_pool_destroy
88 
89 /** Return a new allocator. This function limits the unused memory in the
90  * new allocator to #SVN_ALLOCATOR_RECOMMENDED_MAX_FREE and ensures
91  * proper synchronization if the allocator is used by multiple threads.
92  *
93  * If your application uses multiple threads, creating a separate
94  * allocator for each of these threads may not be feasible. Set the
95  * @a thread_safe parameter to @c TRUE in that case; otherwise, set @a
96  * thread_safe to @c FALSE to maximize performance.
97  *
98  * @note Even if @a thread_safe is @c TRUE, pools themselves will
99  * still not be thread-safe and their access may require explicit
100  * serialization.
101  *
102  * To access the owner pool, which can also serve as the root pool for
103  * your sub-pools, call @c apr_allocator_get_owner().
104  *
105  * @since: New in 1.8
106  */
107 apr_allocator_t *
109 
110 #ifdef __cplusplus
111 }
112 #endif /* __cplusplus */
113 
114 #endif /* SVN_POOLS_H */