contrib/subversion/subversion/include/svn_pools.h

   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 \f
  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 \f
  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 *
 108 svn_pool_create_allocator(svn_boolean_t thread_safe);
 109
 110 #ifdef __cplusplus
 111 }
 112 #endif /* __cplusplus */
 113
 114 #endif /* SVN_POOLS_H */