include/apr_allocator.h

   1 /* Licensed to the Apache Software Foundation (ASF) under one or more
   2  * contributor license agreements.  See the NOTICE file distributed with
   3  * this work for additional information regarding copyright ownership.
   4  * The ASF licenses this file to You under the Apache License, Version 2.0
   5  * (the "License"); you may not use this file except in compliance with
   6  * the License.  You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef APR_ALLOCATOR_H
  18 #define APR_ALLOCATOR_H
  19
  20 /**
  21  * @file apr_allocator.h
  22  * @brief APR Internal Memory Allocation
  23  */
  24
  25 #include "apr.h"
  26 #include "apr_errno.h"
  27 #define APR_WANT_MEMFUNC /**< For no good reason? */
  28 #include "apr_want.h"
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif
  33
  34 /**
  35  * @defgroup apr_allocator Internal Memory Allocation
  36  * @ingroup APR
  37  * @{
  38  */
  39
  40 /** the allocator structure */
  41 typedef struct apr_allocator_t apr_allocator_t;
  42 /** the structure which holds information about the allocation */
  43 typedef struct apr_memnode_t apr_memnode_t;
  44
  45 /** basic memory node structure
  46  * @note The next, ref and first_avail fields are available for use by the
  47  *       caller of apr_allocator_alloc(), the remaining fields are read-only.
  48  *       The next field has to be used with caution and sensibly set when the
  49  *       memnode is passed back to apr_allocator_free().  See apr_allocator_free()
  50  *       for details.
  51  *       The ref and first_avail fields will be properly restored by
  52  *       apr_allocator_free().
  53  */
  54 struct apr_memnode_t {
  55     apr_memnode_t *next;            /**< next memnode */
  56     apr_memnode_t **ref;            /**< reference to self */
  57     apr_uint32_t   index;           /**< size */
  58     apr_uint32_t   free_index;      /**< how much free */
  59     char          *first_avail;     /**< pointer to first free memory */
  60     char          *endp;            /**< pointer to end of free memory */
  61 };
  62
  63 /** The base size of a memory node - aligned.  */
  64 #define APR_MEMNODE_T_SIZE APR_ALIGN_DEFAULT(sizeof(apr_memnode_t))
  65
  66 /** Symbolic constants */
  67 #define APR_ALLOCATOR_MAX_FREE_UNLIMITED 0
  68
  69 /**
  70  * Create a new allocator
  71  * @param allocator The allocator we have just created.
  72  *
  73  */
  74 APR_DECLARE(apr_status_t) apr_allocator_create(apr_allocator_t **allocator)
  75                           __attribute__((nonnull(1)));
  76
  77 /**
  78  * Destroy an allocator
  79  * @param allocator The allocator to be destroyed
  80  * @remark Any memnodes not given back to the allocator prior to destroying
  81  *         will _not_ be free()d.
  82  */
  83 APR_DECLARE(void) apr_allocator_destroy(apr_allocator_t *allocator)
  84                   __attribute__((nonnull(1)));
  85
  86 /**
  87  * Allocate a block of mem from the allocator
  88  * @param allocator The allocator to allocate from
  89  * @param size The size of the mem to allocate (excluding the
  90  *        memnode structure)
  91  */
  92 APR_DECLARE(apr_memnode_t *) apr_allocator_alloc(apr_allocator_t *allocator,
  93                                                  apr_size_t size)
  94                              __attribute__((nonnull(1)));
  95
  96 /**
  97  * Free a list of blocks of mem, giving them back to the allocator.
  98  * The list is typically terminated by a memnode with its next field
  99  * set to NULL.
 100  * @param allocator The allocator to give the mem back to
 101  * @param memnode The memory node to return
 102  */
 103 APR_DECLARE(void) apr_allocator_free(apr_allocator_t *allocator,
 104                                      apr_memnode_t *memnode)
 105                   __attribute__((nonnull(1,2)));
 106
 107 /**
 108  * Get the true size that would be allocated for the given size (including
 109  * the header and alignment).
 110  * @param allocator The allocator from which to the memory would be allocated
 111  * @param size The size to align
 112  * @return The aligned size (or zero on apr_size_t overflow)
 113  */
 114 APR_DECLARE(apr_size_t) apr_allocator_align(apr_allocator_t *allocator,
 115                                             apr_size_t size);
 116
 117 #include "apr_pools.h"
 118
 119 /**
 120  * Set the owner of the allocator
 121  * @param allocator The allocator to set the owner for
 122  * @param pool The pool that is to own the allocator
 123  * @remark Typically pool is the highest level pool using the allocator
 124  */
 125 /*
 126  * XXX: see if we can come up with something a bit better.  Currently
 127  * you can make a pool an owner, but if the pool doesn't use the allocator
 128  * the allocator will never be destroyed.
 129  */
 130 APR_DECLARE(void) apr_allocator_owner_set(apr_allocator_t *allocator,
 131                                           apr_pool_t *pool)
 132                   __attribute__((nonnull(1)));
 133
 134 /**
 135  * Get the current owner of the allocator
 136  * @param allocator The allocator to get the owner from
 137  */
 138 APR_DECLARE(apr_pool_t *) apr_allocator_owner_get(apr_allocator_t *allocator)
 139                           __attribute__((nonnull(1)));
 140
 141 /**
 142  * Set the current threshold at which the allocator should start
 143  * giving blocks back to the system.
 144  * @param allocator The allocator to set the threshold on
 145  * @param size The threshold.  0 == unlimited.
 146  */
 147 APR_DECLARE(void) apr_allocator_max_free_set(apr_allocator_t *allocator,
 148                                              apr_size_t size)
 149                   __attribute__((nonnull(1)));
 150
 151 #include "apr_thread_mutex.h"
 152
 153 #if APR_HAS_THREADS
 154 /**
 155  * Set a mutex for the allocator to use
 156  * @param allocator The allocator to set the mutex for
 157  * @param mutex The mutex
 158  */
 159 APR_DECLARE(void) apr_allocator_mutex_set(apr_allocator_t *allocator,
 160                                           apr_thread_mutex_t *mutex)
 161                   __attribute__((nonnull(1)));
 162
 163 /**
 164  * Get the mutex currently set for the allocator
 165  * @param allocator The allocator
 166  */
 167 APR_DECLARE(apr_thread_mutex_t *) apr_allocator_mutex_get(
 168                                           apr_allocator_t *allocator)
 169                                   __attribute__((nonnull(1)));
 170
 171 #endif /* APR_HAS_THREADS */
 172
 173 /** @} */
 174
 175 #ifdef __cplusplus
 176 }
 177 #endif
 178
 179 #endif /* !APR_ALLOCATOR_H */