Main Page | Modules | Data Structures | File List | Data Fields | Globals | Related Pages

apr_allocator.h

Go to the documentation of this file.
00001 /* Copyright 2000-2004 The Apache Software Foundation
00002  *
00003  * Licensed under the Apache License, Version 2.0 (the "License");
00004  * you may not use this file except in compliance with the License.
00005  * You may obtain a copy of the License at
00006  *
00007  *     http://www.apache.org/licenses/LICENSE-2.0
00008  *
00009  * Unless required by applicable law or agreed to in writing, software
00010  * distributed under the License is distributed on an "AS IS" BASIS,
00011  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00012  * See the License for the specific language governing permissions and
00013  * limitations under the License.
00014  */
00015 
00016 #ifndef APR_ALLOCATOR_H
00017 #define APR_ALLOCATOR_H
00018 
00019 /**
00020  * @file apr_allocator.h
00021  * @brief APR Internal Memory Allocation
00022  */
00023 
00024 #include "apr.h"
00025 #include "apr_errno.h"
00026 #define APR_WANT_MEMFUNC /**< For no good reason? */
00027 #include "apr_want.h"
00028 
00029 #ifdef __cplusplus
00030 extern "C" {
00031 #endif
00032 
00033 /**
00034  * @defgroup apr_allocator Internal Memory Allocation
00035  * @ingroup APR 
00036  * @{
00037  */
00038 
00039 /** the allocator structure */
00040 typedef struct apr_allocator_t apr_allocator_t;
00041 /** the structure which holds information about the allocation */
00042 typedef struct apr_memnode_t apr_memnode_t;
00043 
00044 /** basic memory node structure
00045  * @note The next, ref and first_avail fields are available for use by the
00046  *       caller of apr_allocator_alloc(), the remaining fields are read-only.
00047  *       The next field has to be used with caution and sensibly set when the
00048  *       memnode is passed back to apr_allocator_free().  See apr_allocator_free()
00049  *       for details.  
00050  *       The ref and first_avail fields will be properly restored by
00051  *       apr_allocator_free().
00052  */
00053 struct apr_memnode_t {
00054     apr_memnode_t *next;            /**< next memnode */
00055     apr_memnode_t **ref;            /**< reference to self */
00056     apr_uint32_t   index;           /**< size */
00057     apr_uint32_t   free_index;      /**< how much free */
00058     char          *first_avail;     /**< pointer to first free memory */
00059     char          *endp;            /**< pointer to end of free memory */
00060 };
00061 
00062 /** The base size of a memory node - aligned.  */
00063 #define APR_MEMNODE_T_SIZE APR_ALIGN_DEFAULT(sizeof(apr_memnode_t))
00064 
00065 /** Symbolic constants */
00066 #define APR_ALLOCATOR_MAX_FREE_UNLIMITED 0
00067 
00068 /**
00069  * Create a new allocator
00070  * @param allocator The allocator we have just created.
00071  *
00072  */
00073 APR_DECLARE(apr_status_t) apr_allocator_create(apr_allocator_t **allocator);
00074 
00075 /**
00076  * Destroy an allocator
00077  * @param allocator The allocator to be destroyed
00078  * @remark Any memnodes not given back to the allocator prior to destroying
00079  *         will _not_ be free()d.
00080  */
00081 APR_DECLARE(void) apr_allocator_destroy(apr_allocator_t *allocator);
00082 
00083 /**
00084  * Allocate a block of mem from the allocator
00085  * @param allocator The allocator to allocate from
00086  * @param size The size of the mem to allocate (excluding the
00087  *        memnode structure)
00088  */
00089 APR_DECLARE(apr_memnode_t *) apr_allocator_alloc(apr_allocator_t *allocator,
00090                                                  apr_size_t size);
00091 
00092 /**
00093  * Free a list of blocks of mem, giving them back to the allocator.
00094  * The list is typically terminated by a memnode with its next field
00095  * set to NULL.
00096  * @param allocator The allocator to give the mem back to
00097  * @param memnode The memory node to return
00098  */
00099 APR_DECLARE(void) apr_allocator_free(apr_allocator_t *allocator,
00100                                      apr_memnode_t *memnode);
00101 
00102 #include "apr_pools.h"
00103 
00104 /**
00105  * Set the owner of the allocator
00106  * @param allocator The allocator to set the owner for
00107  * @param pool The pool that is to own the allocator
00108  * @remark Typically pool is the highest level pool using the allocator
00109  */
00110 /*
00111  * XXX: see if we can come up with something a bit better.  Currently
00112  * you can make a pool an owner, but if the pool doesn't use the allocator
00113  * the allocator will never be destroyed.
00114  */
00115 APR_DECLARE(void) apr_allocator_owner_set(apr_allocator_t *allocator,
00116                                           apr_pool_t *pool);
00117 
00118 /**
00119  * Get the current owner of the allocator
00120  * @param allocator The allocator to get the owner from
00121  */
00122 APR_DECLARE(apr_pool_t *) apr_allocator_owner_get(apr_allocator_t *allocator);
00123 
00124 /**
00125  * Set the current threshold at which the allocator should start
00126  * giving blocks back to the system.
00127  * @param allocator The allocator the set the threshold on
00128  * @param size The threshold.  0 == unlimited.
00129  */
00130 APR_DECLARE(void) apr_allocator_max_free_set(apr_allocator_t *allocator,
00131                                              apr_size_t size);
00132 
00133 #include "apr_thread_mutex.h"
00134 
00135 #if APR_HAS_THREADS
00136 /**
00137  * Set a mutex for the allocator to use
00138  * @param allocator The allocator to set the mutex for
00139  * @param mutex The mutex
00140  */
00141 APR_DECLARE(void) apr_allocator_mutex_set(apr_allocator_t *allocator,
00142                                           apr_thread_mutex_t *mutex);
00143 
00144 /**
00145  * Get the mutex currently set for the allocator
00146  * @param allocator The allocator
00147  */
00148 APR_DECLARE(apr_thread_mutex_t *) apr_allocator_mutex_get(
00149                                       apr_allocator_t *allocator);
00150 
00151 #endif /* APR_HAS_THREADS */
00152 
00153 /** @} */
00154 
00155 #ifdef __cplusplus
00156 }
00157 #endif
00158 
00159 #endif /* !APR_ALLOCATOR_H */

Generated on Tue May 10 04:19:07 2005 for Apache Portable Runtime by  doxygen 1.3.9.1