apr_allocator.h revision 302408
11539Srgrimes/* Licensed to the Apache Software Foundation (ASF) under one or more 21539Srgrimes * contributor license agreements. See the NOTICE file distributed with 31539Srgrimes * this work for additional information regarding copyright ownership. 41539Srgrimes * The ASF licenses this file to You under the Apache License, Version 2.0 51539Srgrimes * (the "License"); you may not use this file except in compliance with 61539Srgrimes * the License. You may obtain a copy of the License at 71539Srgrimes * 81539Srgrimes * http://www.apache.org/licenses/LICENSE-2.0 91539Srgrimes * 101539Srgrimes * Unless required by applicable law or agreed to in writing, software 111539Srgrimes * distributed under the License is distributed on an "AS IS" BASIS, 121539Srgrimes * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 131539Srgrimes * See the License for the specific language governing permissions and 141539Srgrimes * limitations under the License. 151539Srgrimes */ 161539Srgrimes 171539Srgrimes#ifndef APR_ALLOCATOR_H 181539Srgrimes#define APR_ALLOCATOR_H 191539Srgrimes 201539Srgrimes/** 211539Srgrimes * @file apr_allocator.h 221539Srgrimes * @brief APR Internal Memory Allocation 231539Srgrimes */ 241539Srgrimes 251539Srgrimes#include "apr.h" 261539Srgrimes#include "apr_errno.h" 271539Srgrimes#define APR_WANT_MEMFUNC /**< For no good reason? */ 281539Srgrimes#include "apr_want.h" 291539Srgrimes 301539Srgrimes#ifdef __cplusplus 311539Srgrimesextern "C" { 321539Srgrimes#endif 331539Srgrimes 341539Srgrimes/** 351539Srgrimes * @defgroup apr_allocator Internal Memory Allocation 361539Srgrimes * @ingroup APR 371539Srgrimes * @{ 381539Srgrimes */ 391539Srgrimes 401539Srgrimes/** the allocator structure */ 411539Srgrimestypedef struct apr_allocator_t apr_allocator_t; 4254746Sphantom/** the structure which holds information about the allocation */ 431539Srgrimestypedef struct apr_memnode_t apr_memnode_t; 441539Srgrimes 457655Sbde/** basic memory node structure 467655Sbde * @note The next, ref and first_avail fields are available for use by the 471539Srgrimes * caller of apr_allocator_alloc(), the remaining fields are read-only. 48103113Smike * The next field has to be used with caution and sensibly set when the 49103113Smike * memnode is passed back to apr_allocator_free(). See apr_allocator_free() 501539Srgrimes * for details. 5157035Sobrien * The ref and first_avail fields will be properly restored by 5257035Sobrien * apr_allocator_free(). 5357035Sobrien */ 5457035Sobrienstruct apr_memnode_t { 5557035Sobrien apr_memnode_t *next; /**< next memnode */ 5657035Sobrien apr_memnode_t **ref; /**< reference to self */ 5757035Sobrien apr_uint32_t index; /**< size */ 5857035Sobrien apr_uint32_t free_index; /**< how much free */ 5957035Sobrien char *first_avail; /**< pointer to first free memory */ 6057035Sobrien char *endp; /**< pointer to end of free memory */ 6157035Sobrien}; 6257035Sobrien 6357035Sobrien/** The base size of a memory node - aligned. */ 6457035Sobrien#define APR_MEMNODE_T_SIZE APR_ALIGN_DEFAULT(sizeof(apr_memnode_t)) 65101984Skeichii 66102093Sache/** Symbolic constants */ 67101984Skeichii#define APR_ALLOCATOR_MAX_FREE_UNLIMITED 0 68101984Skeichii 691539Srgrimes/** 707655Sbde * Create a new allocator 7193032Simp * @param allocator The allocator we have just created. 7293032Simp * 7393032Simp */ 7493032SimpAPR_DECLARE(apr_status_t) apr_allocator_create(apr_allocator_t **allocator) 7593032Simp __attribute__((nonnull(1))); 7693032Simp 7793032Simp/** 7893032Simp * Destroy an allocator 7993032Simp * @param allocator The allocator to be destroyed 8093032Simp * @remark Any memnodes not given back to the allocator prior to destroying 8193032Simp * will _not_ be free()d. 8293032Simp */ 8393032SimpAPR_DECLARE(void) apr_allocator_destroy(apr_allocator_t *allocator) 841539Srgrimes __attribute__((nonnull(1))); 85102998Smike 86102998Smike/** 87102998Smike * Allocate a block of mem from the allocator 88102998Smike * @param allocator The allocator to allocate from 89102998Smike * @param size The size of the mem to allocate (excluding the 90102998Smike * memnode structure) 91102998Smike */ 92102998SmikeAPR_DECLARE(apr_memnode_t *) apr_allocator_alloc(apr_allocator_t *allocator, 9393032Simp apr_size_t size) 9493032Simp __attribute__((nonnull(1))); 9593032Simp 9693032Simp/** 9793032Simp * Free a list of blocks of mem, giving them back to the allocator. 9893032Simp * The list is typically terminated by a memnode with its next field 9993032Simp * set to NULL. 10093032Simp * @param allocator The allocator to give the mem back to 1017655Sbde * @param memnode The memory node to return 1027655Sbde */ 1037655SbdeAPR_DECLARE(void) apr_allocator_free(apr_allocator_t *allocator, 10457035Sobrien apr_memnode_t *memnode) 10557035Sobrien __attribute__((nonnull(1,2))); 10657035Sobrien 10757035Sobrien#include "apr_pools.h" 10857035Sobrien 10957035Sobrien/** 11057035Sobrien * Set the owner of the allocator 11157035Sobrien * @param allocator The allocator to set the owner for 11257035Sobrien * @param pool The pool that is to own the allocator 11357035Sobrien * @remark Typically pool is the highest level pool using the allocator 11457035Sobrien */ 1157655Sbde/* 1167655Sbde * XXX: see if we can come up with something a bit better. Currently 1177655Sbde * you can make a pool an owner, but if the pool doesn't use the allocator 118102998Smike * the allocator will never be destroyed. 119102998Smike */ 120102998SmikeAPR_DECLARE(void) apr_allocator_owner_set(apr_allocator_t *allocator, 121102998Smike apr_pool_t *pool) 122102998Smike __attribute__((nonnull(1))); 123102998Smike 124102998Smike/** 125102998Smike * Get the current owner of the allocator 126102998Smike * @param allocator The allocator to get the owner from 127102998Smike */ 128102998SmikeAPR_DECLARE(apr_pool_t *) apr_allocator_owner_get(apr_allocator_t *allocator) 129102998Smike __attribute__((nonnull(1))); 130102998Smike 131102998Smike/** 132102998Smike * Set the current threshold at which the allocator should start 133102998Smike * giving blocks back to the system. 134102998Smike * @param allocator The allocator to set the threshold on 135102998Smike * @param size The threshold. 0 == unlimited. 136102998Smike */ 13754746SphantomAPR_DECLARE(void) apr_allocator_max_free_set(apr_allocator_t *allocator, 13857035Sobrien apr_size_t size) 13957035Sobrien __attribute__((nonnull(1))); 14057035Sobrien 14157035Sobrien#include "apr_thread_mutex.h" 14257035Sobrien 1437655Sbde#if APR_HAS_THREADS 14457035Sobrien/** 1451539Srgrimes * Set a mutex for the allocator to use 1461539Srgrimes * @param allocator The allocator to set the mutex for 147102998Smike * @param mutex The mutex 1481539Srgrimes */ 149102227SmikeAPR_DECLARE(void) apr_allocator_mutex_set(apr_allocator_t *allocator, 150102227Smike apr_thread_mutex_t *mutex) 151102227Smike __attribute__((nonnull(1))); 1521539Srgrimes 1531539Srgrimes/** 1541539Srgrimes * Get the mutex currently set for the allocator 1557655Sbde * @param allocator The allocator 1567655Sbde */ 1571539SrgrimesAPR_DECLARE(apr_thread_mutex_t *) apr_allocator_mutex_get( 1587655Sbde apr_allocator_t *allocator) 1597655Sbde __attribute__((nonnull(1))); 1607655Sbde 1617655Sbde#endif /* APR_HAS_THREADS */ 1621539Srgrimes 1631539Srgrimes/** @} */ 1647655Sbde 165103113Smike#ifdef __cplusplus 166103113Smike} 167103113Smike#endif 168103113Smike 169103113Smike#endif /* !APR_ALLOCATOR_H */ 170103113Smike