include/apr-0/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 struct apr_memnode_t {
  47     apr_memnode_t *next;            /**< next memnode */
  48     apr_memnode_t **ref;            /**< reference to self */
  49     apr_uint32_t   index;           /**< size */
  50     apr_uint32_t   free_index;      /**< how much free */
  51     char          *first_avail;     /**< pointer to first free memory */
  52     char          *endp;            /**< pointer to end of free memory */
  53 };
  54
  55 /** The base size of a memory node - aligned.  */
  56 #define APR_MEMNODE_T_SIZE APR_ALIGN_DEFAULT(sizeof(apr_memnode_t))
  57
  58 /** Symbolic constants */
  59 #define APR_ALLOCATOR_MAX_FREE_UNLIMITED 0
  60
  61 /**
  62  * Create a new allocator
  63  * @param allocator The allocator we have just created.
  64  *
  65  */
  66 APR_DECLARE(apr_status_t) apr_allocator_create(apr_allocator_t **allocator);
  67
  68 /**
  69  * Destroy an allocator
  70  * @param allocator The allocator to be destroyed
  71  * @remark Any memnodes not given back to the allocator prior to destroying
  72  *         will _not_ be free()d.
  73  */
  74 APR_DECLARE(void) apr_allocator_destroy(apr_allocator_t *allocator);
  75
  76 /**
  77  * Allocate a block of mem from the allocator
  78  * @param allocator The allocator to allocate from
  79  * @param size The size of the mem to allocate (excluding the
  80  *        memnode structure)
  81  */
  82 APR_DECLARE(apr_memnode_t *) apr_allocator_alloc(apr_allocator_t *allocator,
  83                                                  apr_size_t size);
  84
  85 /**
  86  * Free a block of mem, giving it back to the allocator
  87  * @param allocator The allocator to give the mem back to
  88  * @param memnode The memory node to return
  89  */
  90 APR_DECLARE(void) apr_allocator_free(apr_allocator_t *allocator,
  91                                      apr_memnode_t *memnode);
  92
  93 #include "apr_pools.h"
  94
  95 /**
  96  * Set the owner of the allocator
  97  * @param allocator The allocator to set the owner for
  98  * @param pool The pool that is to own the allocator
  99  * @remark Typically pool is the highest level pool using the allocator
 100  */
 101 /*
 102  * XXX: see if we can come up with something a bit better.  Currently
 103  * you can make a pool an owner, but if the pool doesn't use the allocator
 104  * the allocator will never be destroyed.
 105  */
 106 APR_DECLARE(void) apr_allocator_owner_set(apr_allocator_t *allocator,
 107                                           apr_pool_t *pool);
 108
 109 /** @deprecated @see apr_allocator_owner_set */
 110 APR_DECLARE(void) apr_allocator_set_owner(apr_allocator_t *allocator,
 111                                           apr_pool_t *pool);
 112
 113 /**
 114  * Get the current owner of the allocator
 115  * @param allocator The allocator to get the owner from
 116  */
 117 APR_DECLARE(apr_pool_t *) apr_allocator_owner_get(apr_allocator_t *allocator);
 118
 119 /** @deprecated @see apr_allocator_owner_get */
 120 APR_DECLARE(apr_pool_t *) apr_allocator_get_owner(
 121                                   apr_allocator_t *allocator);
 122
 123 /**
 124  * Set the current threshold at which the allocator should start
 125  * giving blocks back to the system.
 126  * @param allocator The allocator the set the threshold on
 127  * @param size The threshold.  0 == unlimited.
 128  */
 129 APR_DECLARE(void) apr_allocator_max_free_set(apr_allocator_t *allocator,
 130                                              apr_size_t size);
 131
 132 /** @deprecated @see apr_allocator_max_free_set */
 133 APR_DECLARE(void) apr_allocator_set_max_free(apr_allocator_t *allocator,
 134                                              apr_size_t size);
 135
 136 #include "apr_thread_mutex.h"
 137
 138 #if APR_HAS_THREADS
 139 /**
 140  * Set a mutex for the allocator to use
 141  * @param allocator The allocator to set the mutex for
 142  * @param mutex The mutex
 143  */
 144 APR_DECLARE(void) apr_allocator_mutex_set(apr_allocator_t *allocator,
 145                                           apr_thread_mutex_t *mutex);
 146
 147 /** @deprecated @see apr_allocator_mutex_set */
 148 APR_DECLARE(void) apr_allocator_set_mutex(apr_allocator_t *allocator,
 149                                           apr_thread_mutex_t *mutex);
 150
 151 /**
 152  * Get the mutex currently set for the allocator
 153  * @param allocator The allocator
 154  */
 155 APR_DECLARE(apr_thread_mutex_t *) apr_allocator_mutex_get(
 156                                       apr_allocator_t *allocator);
 157
 158 /** @deprecated @see apr_allocator_mutex_get */
 159 APR_DECLARE(apr_thread_mutex_t *) apr_allocator_get_mutex(
 160                                       apr_allocator_t *allocator);
 161
 162 #endif /* APR_HAS_THREADS */
 163
 164 /** @} */
 165
 166 #ifdef __cplusplus
 167 }
 168 #endif
 169
 170 #endif /* !APR_ALLOCATOR_H */