contrib/apr/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 #include "apr_pools.h"
 108
 109 /**
 110  * Set the owner of the allocator
 111  * @param allocator The allocator to set the owner for
 112  * @param pool The pool that is to own the allocator
 113  * @remark Typically pool is the highest level pool using the allocator
 114  */
 115 /*
 116  * XXX: see if we can come up with something a bit better.  Currently
 117  * you can make a pool an owner, but if the pool doesn't use the allocator
 118  * the allocator will never be destroyed.
 119  */
 120 APR_DECLARE(void) apr_allocator_owner_set(apr_allocator_t *allocator,
 121                                           apr_pool_t *pool)
 122                   __attribute__((nonnull(1)));
 123
 124 /**
 125  * Get the current owner of the allocator
 126  * @param allocator The allocator to get the owner from
 127  */
 128 APR_DECLARE(apr_pool_t *) apr_allocator_owner_get(apr_allocator_t *allocator)
 129                           __attribute__((nonnull(1)));
 130
 131 /**
 132  * Set the current threshold at which the allocator should start
 133  * giving blocks back to the system.
 134  * @param allocator The allocator the set the threshold on
 135  * @param size The threshold.  0 == unlimited.
 136  */
 137 APR_DECLARE(void) apr_allocator_max_free_set(apr_allocator_t *allocator,
 138                                              apr_size_t size)
 139                   __attribute__((nonnull(1)));
 140
 141 #include "apr_thread_mutex.h"
 142
 143 #if APR_HAS_THREADS
 144 /**
 145  * Set a mutex for the allocator to use
 146  * @param allocator The allocator to set the mutex for
 147  * @param mutex The mutex
 148  */
 149 APR_DECLARE(void) apr_allocator_mutex_set(apr_allocator_t *allocator,
 150                                           apr_thread_mutex_t *mutex)
 151                   __attribute__((nonnull(1)));
 152
 153 /**
 154  * Get the mutex currently set for the allocator
 155  * @param allocator The allocator
 156  */
 157 APR_DECLARE(apr_thread_mutex_t *) apr_allocator_mutex_get(
 158                                           apr_allocator_t *allocator)
 159                                   __attribute__((nonnull(1)));
 160
 161 #endif /* APR_HAS_THREADS */
 162
 163 /** @} */
 164
 165 #ifdef __cplusplus
 166 }
 167 #endif
 168
 169 #endif /* !APR_ALLOCATOR_H */