apr_pools.h revision 302408
198943Sluigi/* Licensed to the Apache Software Foundation (ASF) under one or more 2117328Sluigi * contributor license agreements. See the NOTICE file distributed with 398943Sluigi * this work for additional information regarding copyright ownership. 498943Sluigi * The ASF licenses this file to You under the Apache License, Version 2.0 598943Sluigi * (the "License"); you may not use this file except in compliance with 698943Sluigi * the License. You may obtain a copy of the License at 798943Sluigi * 898943Sluigi * http://www.apache.org/licenses/LICENSE-2.0 998943Sluigi * 1098943Sluigi * Unless required by applicable law or agreed to in writing, software 1198943Sluigi * distributed under the License is distributed on an "AS IS" BASIS, 1298943Sluigi * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 1398943Sluigi * See the License for the specific language governing permissions and 1498943Sluigi * limitations under the License. 1598943Sluigi */ 1698943Sluigi 1798943Sluigi#ifndef APR_POOLS_H 1898943Sluigi#define APR_POOLS_H 1998943Sluigi 2098943Sluigi/** 2198943Sluigi * @file apr_pools.h 2298943Sluigi * @brief APR memory allocation 2398943Sluigi * 2498943Sluigi * Resource allocation routines... 2598943Sluigi * 2698943Sluigi * designed so that we don't have to keep track of EVERYTHING so that 2798943Sluigi * it can be explicitly freed later (a fundamentally unsound strategy --- 2898943Sluigi * particularly in the presence of die()). 2998943Sluigi * 3098943Sluigi * Instead, we maintain pools, and allocate items (both memory and I/O 3198943Sluigi * handlers) from the pools --- currently there are two, one for 3298943Sluigi * per-transaction info, and one for config info. When a transaction is 3398943Sluigi * over, we can delete everything in the per-transaction apr_pool_t without 3498943Sluigi * fear, and without thinking too hard about it either. 3598943Sluigi * 3698943Sluigi * Note that most operations on pools are not thread-safe: a single pool 3798943Sluigi * should only be accessed by a single thread at any given time. The one 3898943Sluigi * exception to this rule is creating a subpool of a given pool: one or more 3998943Sluigi * threads can safely create subpools at the same time that another thread 4098943Sluigi * accesses the parent pool. 4198943Sluigi */ 4298943Sluigi 43117469Sluigi#include "apr.h" 4498943Sluigi#include "apr_errno.h" 4598943Sluigi#include "apr_general.h" /* for APR_STRINGIFY */ 4698943Sluigi#define APR_WANT_MEMFUNC /**< for no good reason? */ 4798943Sluigi#include "apr_want.h" 4898943Sluigi 4998943Sluigi#ifdef __cplusplus 5098943Sluigiextern "C" { 5198943Sluigi#endif 5298943Sluigi 5398943Sluigi/** 5498943Sluigi * @defgroup apr_pools Memory Pool Functions 5598943Sluigi * @ingroup APR 5698943Sluigi * @{ 5798943Sluigi */ 58117328Sluigi 5998943Sluigi/** The fundamental pool type */ 6098943Sluigitypedef struct apr_pool_t apr_pool_t; 6198943Sluigi 6298943Sluigi 6398943Sluigi/** 6498943Sluigi * Declaration helper macro to construct apr_foo_pool_get()s. 6598943Sluigi * 66102098Sluigi * This standardized macro is used by opaque (APR) data types to return 67101628Sluigi * the apr_pool_t that is associated with the data type. 68117328Sluigi * 6998943Sluigi * APR_POOL_DECLARE_ACCESSOR() is used in a header file to declare the 7098943Sluigi * accessor function. A typical usage and result would be: 7198943Sluigi * <pre> 7298943Sluigi * APR_POOL_DECLARE_ACCESSOR(file); 7398943Sluigi * becomes: 74117328Sluigi * APR_DECLARE(apr_pool_t *) apr_file_pool_get(const apr_file_t *thefile); 75117328Sluigi * </pre> 76117328Sluigi * @remark Doxygen unwraps this macro (via doxygen.conf) to provide 77117328Sluigi * actual help for each specific occurrence of apr_foo_pool_get. 78117328Sluigi * @remark the linkage is specified for APR. It would be possible to expand 7998943Sluigi * the macros to support other linkages. 8098943Sluigi */ 8198943Sluigi#define APR_POOL_DECLARE_ACCESSOR(type) \ 82117469Sluigi APR_DECLARE(apr_pool_t *) apr_##type##_pool_get \ 8398943Sluigi (const apr_##type##_t *the##type) 8498943Sluigi 8598943Sluigi/** 8698943Sluigi * Implementation helper macro to provide apr_foo_pool_get()s. 8798943Sluigi * 8898943Sluigi * In the implementation, the APR_POOL_IMPLEMENT_ACCESSOR() is used to 8998943Sluigi * actually define the function. It assumes the field is named "pool". 9098943Sluigi */ 9198943Sluigi#define APR_POOL_IMPLEMENT_ACCESSOR(type) \ 9298943Sluigi APR_DECLARE(apr_pool_t *) apr_##type##_pool_get \ 9398943Sluigi (const apr_##type##_t *the##type) \ 9498943Sluigi { return the##type->pool; } 9598943Sluigi 9698943Sluigi 9798943Sluigi/** 9898943Sluigi * Pool debug levels 9998943Sluigi * 10098943Sluigi * <pre> 10198943Sluigi * | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 10298943Sluigi * --------------------------------- 10398943Sluigi * | | | | | | | | x | General debug code enabled (useful in 10498943Sluigi * combination with --with-efence). 10598943Sluigi * 10698943Sluigi * | | | | | | | x | | Verbose output on stderr (report 10798943Sluigi * CREATE, CLEAR, DESTROY). 10898943Sluigi * 10998943Sluigi * | | | | x | | | | | Verbose output on stderr (report 11098943Sluigi * PALLOC, PCALLOC). 11198943Sluigi * 11298943Sluigi * | | | | | | x | | | Lifetime checking. On each use of a 11398943Sluigi * pool, check its lifetime. If the pool 11498943Sluigi * is out of scope, abort(). 11598943Sluigi * In combination with the verbose flag 11698943Sluigi * above, it will output LIFE in such an 11798943Sluigi * event prior to aborting. 11898943Sluigi * 11998943Sluigi * | | | | | x | | | | Pool owner checking. On each use of a 12098943Sluigi * pool, check if the current thread is the 12198943Sluigi * pool's owner. If not, abort(). In 12298943Sluigi * combination with the verbose flag above, 12398943Sluigi * it will output OWNER in such an event 12498943Sluigi * prior to aborting. Use the debug 12598943Sluigi * function apr_pool_owner_set() to switch 12698943Sluigi * a pool's ownership. 12798943Sluigi * 12898943Sluigi * When no debug level was specified, assume general debug mode. 12998943Sluigi * If level 0 was specified, debugging is switched off. 13098943Sluigi * </pre> 13198943Sluigi */ 13298943Sluigi#if defined(APR_POOL_DEBUG) 13398943Sluigi/* If APR_POOL_DEBUG is blank, we get 1; if it is a number, we get -1. */ 13498943Sluigi#if (APR_POOL_DEBUG - APR_POOL_DEBUG -1 == 1) 13598943Sluigi#undef APR_POOL_DEBUG 13698943Sluigi#define APR_POOL_DEBUG 1 13798943Sluigi#endif 13898943Sluigi#else 13998943Sluigi#define APR_POOL_DEBUG 0 14098943Sluigi#endif 14198943Sluigi 14298943Sluigi/** the place in the code where the particular function was called */ 14398943Sluigi#define APR_POOL__FILE_LINE__ __FILE__ ":" APR_STRINGIFY(__LINE__) 14498943Sluigi 14598943Sluigi 14698943Sluigi 14798943Sluigi/** A function that is called when allocation fails. */ 14898943Sluigitypedef int (*apr_abortfunc_t)(int retcode); 14998943Sluigi 15098943Sluigi/* 15198943Sluigi * APR memory structure manipulators (pools, tables, and arrays). 15298943Sluigi */ 15398943Sluigi 15498943Sluigi/* 15598943Sluigi * Initialization 15698943Sluigi */ 15798943Sluigi 15898943Sluigi/** 15998943Sluigi * Setup all of the internal structures required to use pools 16098943Sluigi * @remark Programs do NOT need to call this directly. APR will call this 16198943Sluigi * automatically from apr_initialize. 16298943Sluigi * @internal 16398943Sluigi */ 16498943SluigiAPR_DECLARE(apr_status_t) apr_pool_initialize(void); 16598943Sluigi 16698943Sluigi/** 16798943Sluigi * Tear down all of the internal structures required to use pools 16898943Sluigi * @remark Programs do NOT need to call this directly. APR will call this 16998943Sluigi * automatically from apr_terminate. 17098943Sluigi * @internal 17198943Sluigi */ 17298943SluigiAPR_DECLARE(void) apr_pool_terminate(void); 17398943Sluigi 17498943Sluigi 17598943Sluigi/* 17698943Sluigi * Pool creation/destruction 17798943Sluigi */ 17898943Sluigi 17998943Sluigi#include "apr_allocator.h" 18098943Sluigi 18198943Sluigi/** 182101641Sluigi * Create a new pool. 183101641Sluigi * @param newpool The pool we have just created. 18498943Sluigi * @param parent The parent pool. If this is NULL, the new pool is a root 18598943Sluigi * pool. If it is non-NULL, the new pool will inherit all 18698943Sluigi * of its parent pool's attributes, except the apr_pool_t will 18798943Sluigi * be a sub-pool. 18898943Sluigi * @param abort_fn A function to use if the pool cannot allocate more memory. 18998943Sluigi * @param allocator The allocator to use with the new pool. If NULL the 19098943Sluigi * allocator of the parent pool will be used. 19198943Sluigi * @remark This function is thread-safe, in the sense that multiple threads 19298943Sluigi * can safely create subpools of the same parent pool concurrently. 19398943Sluigi * Similarly, a subpool can be created by one thread at the same 19498943Sluigi * time that another thread accesses the parent pool. 19598943Sluigi */ 19698943SluigiAPR_DECLARE(apr_status_t) apr_pool_create_ex(apr_pool_t **newpool, 19798943Sluigi apr_pool_t *parent, 19898943Sluigi apr_abortfunc_t abort_fn, 19998943Sluigi apr_allocator_t *allocator) 20098943Sluigi __attribute__((nonnull(1))); 20198943Sluigi 20298943Sluigi/** 20398943Sluigi * Create a new pool. 20498943Sluigi * @deprecated @see apr_pool_create_unmanaged_ex. 20598943Sluigi */ 20698943SluigiAPR_DECLARE(apr_status_t) apr_pool_create_core_ex(apr_pool_t **newpool, 20798943Sluigi apr_abortfunc_t abort_fn, 20898943Sluigi apr_allocator_t *allocator); 20998943Sluigi 21098943Sluigi/** 21198943Sluigi * Create a new unmanaged pool. 21298943Sluigi * @param newpool The pool we have just created. 21398943Sluigi * @param abort_fn A function to use if the pool cannot allocate more memory. 21498943Sluigi * @param allocator The allocator to use with the new pool. If NULL a 21598943Sluigi * new allocator will be created with the new pool as owner. 21698943Sluigi * @remark An unmanaged pool is a special pool without a parent; it will 21798943Sluigi * NOT be destroyed upon apr_terminate. It must be explicitly 21898943Sluigi * destroyed by calling apr_pool_destroy, to prevent memory leaks. 21998943Sluigi * Use of this function is discouraged, think twice about whether 22098943Sluigi * you really really need it. 22198943Sluigi * @warning Any child cleanups registered against the new pool, or 22298943Sluigi * against sub-pools thereof, will not be executed during an 22398943Sluigi * invocation of apr_proc_create(), so resources created in an 22498943Sluigi * "unmanaged" pool hierarchy will leak to child processes. 225102087Sluigi */ 226102087SluigiAPR_DECLARE(apr_status_t) apr_pool_create_unmanaged_ex(apr_pool_t **newpool, 227112250Scjc apr_abortfunc_t abort_fn, 228117241Sluigi apr_allocator_t *allocator) 229117469Sluigi __attribute__((nonnull(1))); 23098943Sluigi 23198943Sluigi/** 232101978Sluigi * Debug version of apr_pool_create_ex. 23398943Sluigi * @param newpool @see apr_pool_create. 23498943Sluigi * @param parent @see apr_pool_create. 23598943Sluigi * @param abort_fn @see apr_pool_create. 23698943Sluigi * @param allocator @see apr_pool_create. 23798943Sluigi * @param file_line Where the function is called from. 23898943Sluigi * This is usually APR_POOL__FILE_LINE__. 23998943Sluigi * @remark Only available when APR_POOL_DEBUG is defined. 24098943Sluigi * Call this directly if you have your apr_pool_create_ex 24198943Sluigi * calls in a wrapper function and wish to override 24298943Sluigi * the file_line argument to reflect the caller of 24398943Sluigi * your wrapper function. If you do not have 24498943Sluigi * apr_pool_create_ex in a wrapper, trust the macro 24598943Sluigi * and don't call apr_pool_create_ex_debug directly. 24698943Sluigi */ 24798943SluigiAPR_DECLARE(apr_status_t) apr_pool_create_ex_debug(apr_pool_t **newpool, 24898943Sluigi apr_pool_t *parent, 24998943Sluigi apr_abortfunc_t abort_fn, 25098943Sluigi apr_allocator_t *allocator, 251101978Sluigi const char *file_line) 25298943Sluigi __attribute__((nonnull(1))); 25398943Sluigi 25498943Sluigi#if APR_POOL_DEBUG 25598943Sluigi#define apr_pool_create_ex(newpool, parent, abort_fn, allocator) \ 25698943Sluigi apr_pool_create_ex_debug(newpool, parent, abort_fn, allocator, \ 25798943Sluigi APR_POOL__FILE_LINE__) 25898943Sluigi#endif 25998943Sluigi 26098943Sluigi/** 26198943Sluigi * Debug version of apr_pool_create_core_ex. 26298943Sluigi * @deprecated @see apr_pool_create_unmanaged_ex_debug. 26398943Sluigi */ 26498943SluigiAPR_DECLARE(apr_status_t) apr_pool_create_core_ex_debug(apr_pool_t **newpool, 26598943Sluigi apr_abortfunc_t abort_fn, 26698943Sluigi apr_allocator_t *allocator, 26799475Sluigi const char *file_line); 26898943Sluigi 26998943Sluigi/** 270117328Sluigi * Debug version of apr_pool_create_unmanaged_ex. 27198943Sluigi * @param newpool @see apr_pool_create_unmanaged. 27298943Sluigi * @param abort_fn @see apr_pool_create_unmanaged. 27398943Sluigi * @param allocator @see apr_pool_create_unmanaged. 27498943Sluigi * @param file_line Where the function is called from. 27598943Sluigi * This is usually APR_POOL__FILE_LINE__. 27698943Sluigi * @remark Only available when APR_POOL_DEBUG is defined. 27798943Sluigi * Call this directly if you have your apr_pool_create_unmanaged_ex 27898943Sluigi * calls in a wrapper function and wish to override 27998943Sluigi * the file_line argument to reflect the caller of 28098943Sluigi * your wrapper function. If you do not have 28198943Sluigi * apr_pool_create_core_ex in a wrapper, trust the macro 28298943Sluigi * and don't call apr_pool_create_core_ex_debug directly. 28398943Sluigi */ 28498943SluigiAPR_DECLARE(apr_status_t) apr_pool_create_unmanaged_ex_debug(apr_pool_t **newpool, 28598943Sluigi apr_abortfunc_t abort_fn, 28698943Sluigi apr_allocator_t *allocator, 28798943Sluigi const char *file_line) 28898943Sluigi __attribute__((nonnull(1))); 28998943Sluigi 29099475Sluigi#if APR_POOL_DEBUG 29198943Sluigi#define apr_pool_create_core_ex(newpool, abort_fn, allocator) \ 292117469Sluigi apr_pool_create_unmanaged_ex_debug(newpool, abort_fn, allocator, \ 293117328Sluigi APR_POOL__FILE_LINE__) 29498943Sluigi 29598943Sluigi#define apr_pool_create_unmanaged_ex(newpool, abort_fn, allocator) \ 29698943Sluigi apr_pool_create_unmanaged_ex_debug(newpool, abort_fn, allocator, \ 29798943Sluigi APR_POOL__FILE_LINE__) 29898943Sluigi 29998943Sluigi#endif 30098943Sluigi 30198943Sluigi/** 30298943Sluigi * Create a new pool. 30398943Sluigi * @param newpool The pool we have just created. 30498943Sluigi * @param parent The parent pool. If this is NULL, the new pool is a root 30598943Sluigi * pool. If it is non-NULL, the new pool will inherit all 30698943Sluigi * of its parent pool's attributes, except the apr_pool_t will 30798943Sluigi * be a sub-pool. 30898943Sluigi * @remark This function is thread-safe, in the sense that multiple threads 30998943Sluigi * can safely create subpools of the same parent pool concurrently. 31098943Sluigi * Similarly, a subpool can be created by one thread at the same 31198943Sluigi * time that another thread accesses the parent pool. 31298943Sluigi */ 31398943Sluigi#if defined(DOXYGEN) 31498943SluigiAPR_DECLARE(apr_status_t) apr_pool_create(apr_pool_t **newpool, 31598943Sluigi apr_pool_t *parent); 31698943Sluigi#else 31798943Sluigi#if APR_POOL_DEBUG 31898943Sluigi#define apr_pool_create(newpool, parent) \ 31998943Sluigi apr_pool_create_ex_debug(newpool, parent, NULL, NULL, \ 32098943Sluigi APR_POOL__FILE_LINE__) 32198943Sluigi#else 32298943Sluigi#define apr_pool_create(newpool, parent) \ 32398943Sluigi apr_pool_create_ex(newpool, parent, NULL, NULL) 32498943Sluigi#endif 32598943Sluigi#endif 32698943Sluigi 32798943Sluigi/** 32898943Sluigi * Create a new unmanaged pool. 32999909Sluigi * @param newpool The pool we have just created. 33098943Sluigi */ 331102087Sluigi#if defined(DOXYGEN) 332102087SluigiAPR_DECLARE(apr_status_t) apr_pool_create_core(apr_pool_t **newpool); 333102087SluigiAPR_DECLARE(apr_status_t) apr_pool_create_unmanaged(apr_pool_t **newpool); 334102087Sluigi#else 335102087Sluigi#if APR_POOL_DEBUG 336102087Sluigi#define apr_pool_create_core(newpool) \ 337102087Sluigi apr_pool_create_unmanaged_ex_debug(newpool, NULL, NULL, \ 338102087Sluigi APR_POOL__FILE_LINE__) 339112250Scjc#define apr_pool_create_unmanaged(newpool) \ 340117241Sluigi apr_pool_create_unmanaged_ex_debug(newpool, NULL, NULL, \ 341117469Sluigi APR_POOL__FILE_LINE__) 34298943Sluigi#else 34398943Sluigi#define apr_pool_create_core(newpool) \ 34498943Sluigi apr_pool_create_unmanaged_ex(newpool, NULL, NULL) 34598943Sluigi#define apr_pool_create_unmanaged(newpool) \ 34698943Sluigi apr_pool_create_unmanaged_ex(newpool, NULL, NULL) 347101641Sluigi#endif 348101641Sluigi#endif 349101641Sluigi 350101641Sluigi/** 351117328Sluigi * Find the pool's allocator 35298943Sluigi * @param pool The pool to get the allocator from. 35398943Sluigi */ 354117328SluigiAPR_DECLARE(apr_allocator_t *) apr_pool_allocator_get(apr_pool_t *pool) 355117328Sluigi __attribute__((nonnull(1))); 356117328Sluigi 357115793Sticso/** 358115793Sticso * Clear all memory in the pool and run all the cleanups. This also destroys all 359115793Sticso * subpools. 360115793Sticso * @param p The pool to clear 361115793Sticso * @remark This does not actually free the memory, it just allows the pool 362117328Sluigi * to re-use this memory for the next allocation. 363117328Sluigi * @see apr_pool_destroy() 364117328Sluigi */ 365117469SluigiAPR_DECLARE(void) apr_pool_clear(apr_pool_t *p) __attribute__((nonnull(1))); 366117328Sluigi 367117328Sluigi/** 368117328Sluigi * Debug version of apr_pool_clear. 369117328Sluigi * @param p See: apr_pool_clear. 370117577Sluigi * @param file_line Where the function is called from. 371117328Sluigi * This is usually APR_POOL__FILE_LINE__. 372117328Sluigi * @remark Only available when APR_POOL_DEBUG is defined. 373117328Sluigi * Call this directly if you have your apr_pool_clear 374117328Sluigi * calls in a wrapper function and wish to override 375117328Sluigi * the file_line argument to reflect the caller of 376117328Sluigi * your wrapper function. If you do not have 377117328Sluigi * apr_pool_clear in a wrapper, trust the macro 378117328Sluigi * and don't call apr_pool_destroy_clear directly. 379117328Sluigi */ 380117328SluigiAPR_DECLARE(void) apr_pool_clear_debug(apr_pool_t *p, 381117328Sluigi const char *file_line) 382117328Sluigi __attribute__((nonnull(1))); 383117328Sluigi 384117328Sluigi#if APR_POOL_DEBUG 385117328Sluigi#define apr_pool_clear(p) \ 386117328Sluigi apr_pool_clear_debug(p, APR_POOL__FILE_LINE__) 387117328Sluigi#endif 38898943Sluigi 38998943Sluigi/** 390117328Sluigi * Destroy the pool. This takes similar action as apr_pool_clear() and then 39198943Sluigi * frees all the memory. 39298943Sluigi * @param p The pool to destroy 39398943Sluigi * @remark This will actually free the memory 39498943Sluigi */ 39598943SluigiAPR_DECLARE(void) apr_pool_destroy(apr_pool_t *p) __attribute__((nonnull(1))); 396117469Sluigi 39798943Sluigi/** 39898943Sluigi * Debug version of apr_pool_destroy. 39998943Sluigi * @param p See: apr_pool_destroy. 40098943Sluigi * @param file_line Where the function is called from. 40198943Sluigi * This is usually APR_POOL__FILE_LINE__. 40298943Sluigi * @remark Only available when APR_POOL_DEBUG is defined. 40398943Sluigi * Call this directly if you have your apr_pool_destroy 404117328Sluigi * calls in a wrapper function and wish to override 405117328Sluigi * the file_line argument to reflect the caller of 406117328Sluigi * your wrapper function. If you do not have 407117328Sluigi * apr_pool_destroy in a wrapper, trust the macro 408117469Sluigi * and don't call apr_pool_destroy_debug directly. 409117469Sluigi */ 41098943SluigiAPR_DECLARE(void) apr_pool_destroy_debug(apr_pool_t *p, 41198943Sluigi const char *file_line) 41298943Sluigi __attribute__((nonnull(1))); 41398943Sluigi 41498943Sluigi#if APR_POOL_DEBUG 41598943Sluigi#define apr_pool_destroy(p) \ 41698943Sluigi apr_pool_destroy_debug(p, APR_POOL__FILE_LINE__) 41798943Sluigi#endif 41898943Sluigi 41998943Sluigi 42098943Sluigi/* 421117328Sluigi * Memory allocation 42298943Sluigi */ 42398943Sluigi 42498943Sluigi/** 425117469Sluigi * Allocate a block of memory from a pool 42698943Sluigi * @param p The pool to allocate from 42798943Sluigi * @param size The amount of memory to allocate 42898943Sluigi * @return The allocated memory 42998943Sluigi */ 43098943SluigiAPR_DECLARE(void *) apr_palloc(apr_pool_t *p, apr_size_t size) 43198943Sluigi#if defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4)) 43298943Sluigi __attribute__((alloc_size(2))) 43398943Sluigi#endif 43498943Sluigi __attribute__((nonnull(1))); 43598943Sluigi 43698943Sluigi/** 43798943Sluigi * Debug version of apr_palloc 43898943Sluigi * @param p See: apr_palloc 43998943Sluigi * @param size See: apr_palloc 44098943Sluigi * @param file_line Where the function is called from. 44198943Sluigi * This is usually APR_POOL__FILE_LINE__. 44298943Sluigi * @return See: apr_palloc 44398943Sluigi */ 44498943SluigiAPR_DECLARE(void *) apr_palloc_debug(apr_pool_t *p, apr_size_t size, 445117328Sluigi const char *file_line) 446117328Sluigi#if defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4)) 447117328Sluigi __attribute__((alloc_size(2))) 448117328Sluigi#endif 449117328Sluigi __attribute__((nonnull(1))); 450117328Sluigi 451117328Sluigi#if APR_POOL_DEBUG 452117328Sluigi#define apr_palloc(p, size) \ 453117328Sluigi apr_palloc_debug(p, size, APR_POOL__FILE_LINE__) 454117328Sluigi#endif 45598943Sluigi 456117328Sluigi/** 45798943Sluigi * Allocate a block of memory from a pool and set all of the memory to 0 45898943Sluigi * @param p The pool to allocate from 45998943Sluigi * @param size The amount of memory to allocate 460102087Sluigi * @return The allocated memory 46198943Sluigi */ 462117328Sluigi#if defined(DOXYGEN) 46398943SluigiAPR_DECLARE(void *) apr_pcalloc(apr_pool_t *p, apr_size_t size); 464117469Sluigi#elif !APR_POOL_DEBUG 46598943Sluigi#define apr_pcalloc(p, size) memset(apr_palloc(p, size), 0, size) 46698943Sluigi#endif 46798943Sluigi 468116690Sluigi/** 469117328Sluigi * Debug version of apr_pcalloc 470117328Sluigi * @param p See: apr_pcalloc 471116690Sluigi * @param size See: apr_pcalloc 472116690Sluigi * @param file_line Where the function is called from. 473116690Sluigi * This is usually APR_POOL__FILE_LINE__. 474116690Sluigi * @return See: apr_pcalloc 47598943Sluigi */ 47698943SluigiAPR_DECLARE(void *) apr_pcalloc_debug(apr_pool_t *p, apr_size_t size, 47798943Sluigi const char *file_line) 47898943Sluigi __attribute__((nonnull(1))); 47998943Sluigi 48098943Sluigi#if APR_POOL_DEBUG 48198943Sluigi#define apr_pcalloc(p, size) \ 48298943Sluigi apr_pcalloc_debug(p, size, APR_POOL__FILE_LINE__) 48398943Sluigi#endif 48498943Sluigi 48598943Sluigi 48698943Sluigi/* 48798943Sluigi * Pool Properties 48898943Sluigi */ 48998943Sluigi 49098943Sluigi/** 49198943Sluigi * Set the function to be called when an allocation failure occurs. 49298943Sluigi * @remark If the program wants APR to exit on a memory allocation error, 493101628Sluigi * then this function can be called to set the callback to use (for 49498943Sluigi * performing cleanup and then exiting). If this function is not called, 49598943Sluigi * then APR will return an error and expect the calling program to 49698943Sluigi * deal with the error accordingly. 49798943Sluigi */ 498101628SluigiAPR_DECLARE(void) apr_pool_abort_set(apr_abortfunc_t abortfunc, 499101628Sluigi apr_pool_t *pool) 50098943Sluigi __attribute__((nonnull(2))); 50198943Sluigi 502101628Sluigi/** 503117577Sluigi * Get the abort function associated with the specified pool. 504101628Sluigi * @param pool The pool for retrieving the abort function. 505106505Smaxim * @return The abort function for the given pool. 50698943Sluigi */ 50798943SluigiAPR_DECLARE(apr_abortfunc_t) apr_pool_abort_get(apr_pool_t *pool) 50898943Sluigi __attribute__((nonnull(1))); 50998943Sluigi 510101628Sluigi/** 51198943Sluigi * Get the parent pool of the specified pool. 512101628Sluigi * @param pool The pool for retrieving the parent pool. 513101628Sluigi * @return The parent of the given pool. 514101628Sluigi */ 51598943SluigiAPR_DECLARE(apr_pool_t *) apr_pool_parent_get(apr_pool_t *pool) 516101628Sluigi __attribute__((nonnull(1))); 517101628Sluigi 518101628Sluigi/** 519101628Sluigi * Determine if pool a is an ancestor of pool b. 520101628Sluigi * @param a The pool to search 521101628Sluigi * @param b The pool to search for 522101628Sluigi * @return True if a is an ancestor of b, NULL is considered an ancestor 523101628Sluigi * of all pools. 524117577Sluigi * @remark if compiled with APR_POOL_DEBUG, this function will also 525101628Sluigi * return true if A is a pool which has been guaranteed by the caller 526101628Sluigi * (using apr_pool_join) to have a lifetime at least as long as some 527101628Sluigi * ancestor of pool B. 52898943Sluigi */ 529101628SluigiAPR_DECLARE(int) apr_pool_is_ancestor(apr_pool_t *a, apr_pool_t *b); 530101628Sluigi 531101628Sluigi/** 53298943Sluigi * Tag a pool (give it a name) 53398943Sluigi * @param pool The pool to tag 53498943Sluigi * @param tag The tag 53598943Sluigi */ 53698943SluigiAPR_DECLARE(void) apr_pool_tag(apr_pool_t *pool, const char *tag) 53798943Sluigi __attribute__((nonnull(1))); 53898943Sluigi 53998943Sluigi 54098943Sluigi/* 54198943Sluigi * User data management 542101628Sluigi */ 543101628Sluigi 54498943Sluigi/** 54598943Sluigi * Set the data associated with the current pool 54698943Sluigi * @param data The user data associated with the pool. 54798943Sluigi * @param key The key to use for association 54898943Sluigi * @param cleanup The cleanup program to use to cleanup the data (NULL if none) 549101628Sluigi * @param pool The current pool 55098943Sluigi * @warning The data to be attached to the pool should have a life span 55198943Sluigi * at least as long as the pool it is being attached to. 55298943Sluigi * 553117328Sluigi * Users of APR must take EXTREME care when choosing a key to 55498943Sluigi * use for their data. It is possible to accidentally overwrite 55598943Sluigi * data by choosing a key that another part of the program is using. 55698943Sluigi * Therefore it is advised that steps are taken to ensure that unique 55798943Sluigi * keys are used for all of the userdata objects in a particular pool 558117328Sluigi * (the same key in two different pools or a pool and one of its 55998943Sluigi * subpools is okay) at all times. Careful namespace prefixing of 560102087Sluigi * key names is a typical way to help ensure this uniqueness. 56198943Sluigi * 562102087Sluigi */ 56398943SluigiAPR_DECLARE(apr_status_t) apr_pool_userdata_set(const void *data, 56498943Sluigi const char *key, 56598943Sluigi apr_status_t (*cleanup)(void *), 56698943Sluigi apr_pool_t *pool) 56798943Sluigi __attribute__((nonnull(2,4))); 56898943Sluigi 56998943Sluigi/** 57098943Sluigi * Set the data associated with the current pool 57198943Sluigi * @param data The user data associated with the pool. 57298943Sluigi * @param key The key to use for association 573117328Sluigi * @param cleanup The cleanup program to use to cleanup the data (NULL if none) 57498943Sluigi * @param pool The current pool 575117328Sluigi * @note same as apr_pool_userdata_set(), except that this version doesn't 576101978Sluigi * make a copy of the key (this function is useful, for example, when 577101978Sluigi * the key is a string literal) 578102087Sluigi * @warning This should NOT be used if the key could change addresses by 579102087Sluigi * any means between the apr_pool_userdata_setn() call and a 58098943Sluigi * subsequent apr_pool_userdata_get() on that key, such as if a 58198943Sluigi * static string is used as a userdata key in a DSO and the DSO could 58298943Sluigi * be unloaded and reloaded between the _setn() and the _get(). You 58398943Sluigi * MUST use apr_pool_userdata_set() in such cases. 584102087Sluigi * @warning More generally, the key and the data to be attached to the 58598943Sluigi * pool should have a life span at least as long as the pool itself. 58698943Sluigi * 58798943Sluigi */ 58898943SluigiAPR_DECLARE(apr_status_t) apr_pool_userdata_setn( 58998943Sluigi const void *data, const char *key, 59098943Sluigi apr_status_t (*cleanup)(void *), 59198943Sluigi apr_pool_t *pool) 59298943Sluigi __attribute__((nonnull(2,4))); 59398943Sluigi 59498943Sluigi/** 59598943Sluigi * Return the data associated with the current pool. 59698943Sluigi * @param data The user data associated with the pool. 59798943Sluigi * @param key The key for the data to retrieve 59898943Sluigi * @param pool The current pool. 59998943Sluigi */ 60098943SluigiAPR_DECLARE(apr_status_t) apr_pool_userdata_get(void **data, const char *key, 60198943Sluigi apr_pool_t *pool) 60298943Sluigi __attribute__((nonnull(1,2,3))); 60398943Sluigi 60498943Sluigi 60598943Sluigi/** 60698943Sluigi * @defgroup PoolCleanup Pool Cleanup Functions 60798943Sluigi * 60898943Sluigi * Cleanups are performed in the reverse order they were registered. That is: 60998943Sluigi * Last In, First Out. A cleanup function can safely allocate memory from 61098943Sluigi * the pool that is being cleaned up. It can also safely register additional 61198943Sluigi * cleanups which will be run LIFO, directly after the current cleanup 61298943Sluigi * terminates. Cleanups have to take caution in calling functions that 61398943Sluigi * create subpools. Subpools, created during cleanup will NOT automatically 61498943Sluigi * be cleaned up. In other words, cleanups are to clean up after themselves. 61598943Sluigi * 61698943Sluigi * @{ 61798943Sluigi */ 61898943Sluigi 619102087Sluigi/** 62098943Sluigi * Register a function to be called when a pool is cleared or destroyed 62198943Sluigi * @param p The pool to register the cleanup with 62298943Sluigi * @param data The data to pass to the cleanup function. 62398943Sluigi * @param plain_cleanup The function to call when the pool is cleared 62498943Sluigi * or destroyed 62598943Sluigi * @param child_cleanup The function to call when a child process is about 626117328Sluigi * to exec - this function is called in the child, obviously! 62798943Sluigi */ 628117469SluigiAPR_DECLARE(void) apr_pool_cleanup_register( 62998943Sluigi apr_pool_t *p, const void *data, 63098943Sluigi apr_status_t (*plain_cleanup)(void *), 63199475Sluigi apr_status_t (*child_cleanup)(void *)) 63298943Sluigi __attribute__((nonnull(3,4))); 63399475Sluigi 63498943Sluigi/** 63598943Sluigi * Register a function to be called when a pool is cleared or destroyed. 63698943Sluigi * 63798943Sluigi * Unlike apr_pool_cleanup_register which registers a cleanup 63898943Sluigi * that is called AFTER all subpools are destroyed, this function registers 63998943Sluigi * a function that will be called before any of the subpools are destroyed. 64098943Sluigi * 64198943Sluigi * @param p The pool to register the cleanup with 64298943Sluigi * @param data The data to pass to the cleanup function. 64398943Sluigi * @param plain_cleanup The function to call when the pool is cleared 64498943Sluigi * or destroyed 64598943Sluigi */ 64698943SluigiAPR_DECLARE(void) apr_pool_pre_cleanup_register( 64798943Sluigi apr_pool_t *p, const void *data, 648117577Sluigi apr_status_t (*plain_cleanup)(void *)) 64998943Sluigi __attribute__((nonnull(3))); 65098943Sluigi 651117577Sluigi/** 65298943Sluigi * Remove a previously registered cleanup function. 65398943Sluigi * 65498943Sluigi * The cleanup most recently registered with @a p having the same values of 65598943Sluigi * @a data and @a cleanup will be removed. 65698943Sluigi * 65798943Sluigi * @param p The pool to remove the cleanup from 65898943Sluigi * @param data The data of the registered cleanup 65998943Sluigi * @param cleanup The function to remove from cleanup 66098943Sluigi * @remarks For some strange reason only the plain_cleanup is handled by this 66198943Sluigi * function 66298943Sluigi */ 66398943SluigiAPR_DECLARE(void) apr_pool_cleanup_kill(apr_pool_t *p, const void *data, 66498943Sluigi apr_status_t (*cleanup)(void *)) 66598943Sluigi __attribute__((nonnull(3))); 666117469Sluigi 66798943Sluigi/** 668117469Sluigi * Replace the child cleanup function of a previously registered cleanup. 66998943Sluigi * 670117577Sluigi * The cleanup most recently registered with @a p having the same values of 671117577Sluigi * @a data and @a plain_cleanup will have the registered child cleanup 67298943Sluigi * function replaced with @a child_cleanup. 67398943Sluigi * 67498943Sluigi * @param p The pool of the registered cleanup 67598943Sluigi * @param data The data of the registered cleanup 67698943Sluigi * @param plain_cleanup The plain cleanup function of the registered cleanup 67798943Sluigi * @param child_cleanup The function to register as the child cleanup 67898943Sluigi */ 67998943SluigiAPR_DECLARE(void) apr_pool_child_cleanup_set( 68098943Sluigi apr_pool_t *p, const void *data, 68198943Sluigi apr_status_t (*plain_cleanup)(void *), 68298943Sluigi apr_status_t (*child_cleanup)(void *)) 68398943Sluigi __attribute__((nonnull(3,4))); 68498943Sluigi 68598943Sluigi/** 68698943Sluigi * Run the specified cleanup function immediately and unregister it. 68798943Sluigi * 68898943Sluigi * The cleanup most recently registered with @a p having the same values of 68998943Sluigi * @a data and @a cleanup will be removed and @a cleanup will be called 69098943Sluigi * with @a data as the argument. 69198943Sluigi * 69298943Sluigi * @param p The pool to remove the cleanup from 69398943Sluigi * @param data The data to remove from cleanup 69498943Sluigi * @param cleanup The function to remove from cleanup 69598943Sluigi */ 69698943SluigiAPR_DECLARE(apr_status_t) apr_pool_cleanup_run(apr_pool_t *p, void *data, 697117469Sluigi apr_status_t (*cleanup)(void *)) 69898943Sluigi __attribute__((nonnull(3))); 69998943Sluigi 700117328Sluigi/** 701117328Sluigi * An empty cleanup function. 70298943Sluigi * 703102087Sluigi * Passed to apr_pool_cleanup_register() when no cleanup is required. 70498943Sluigi * 70598943Sluigi * @param data The data to cleanup, will not be used by this function. 70698943Sluigi */ 70798943SluigiAPR_DECLARE_NONSTD(apr_status_t) apr_pool_cleanup_null(void *data); 70898943Sluigi 70998943Sluigi/** 710117328Sluigi * Run all registered child cleanups, in preparation for an exec() 711116716Sluigi * call in a forked child -- close files, etc., but *don't* flush I/O 71298943Sluigi * buffers, *don't* wait for subprocesses, and *don't* free any 71398943Sluigi * memory. 71498943Sluigi */ 71598943SluigiAPR_DECLARE(void) apr_pool_cleanup_for_exec(void); 71698943Sluigi 71798943Sluigi/** @} */ 718117577Sluigi 71998943Sluigi/** 72098943Sluigi * @defgroup PoolDebug Pool Debugging functions. 721116716Sluigi * 722116716Sluigi * pools have nested lifetimes -- sub_pools are destroyed when the 723116716Sluigi * parent pool is cleared. We allow certain liberties with operations 724116716Sluigi * on things such as tables (and on other structures in a more general 725116716Sluigi * sense) where we allow the caller to insert values into a table which 726116716Sluigi * were not allocated from the table's pool. The table's data will 72798943Sluigi * remain valid as long as all the pools from which its values are 728117328Sluigi * allocated remain valid. 729116716Sluigi * 730117328Sluigi * For example, if B is a sub pool of A, and you build a table T in 731116716Sluigi * pool B, then it's safe to insert data allocated in A or B into T 73298943Sluigi * (because B lives at most as long as A does, and T is destroyed when 733116716Sluigi * B is cleared/destroyed). On the other hand, if S is a table in 734116716Sluigi * pool A, it is safe to insert data allocated in A into S, but it 735116716Sluigi * is *not safe* to insert data allocated from B into S... because 736116716Sluigi * B can be cleared/destroyed before A is (which would leave dangling 73798943Sluigi * pointers in T's data structures). 73898943Sluigi * 73998943Sluigi * In general we say that it is safe to insert data into a table T 74098943Sluigi * if the data is allocated in any ancestor of T's pool. This is the 74198943Sluigi * basis on which the APR_POOL_DEBUG code works -- it tests these ancestor 742117328Sluigi * relationships for all data inserted into tables. APR_POOL_DEBUG also 743117328Sluigi * provides tools (apr_pool_find, and apr_pool_is_ancestor) for other 744117328Sluigi * folks to implement similar restrictions for their own data 745117328Sluigi * structures. 746117328Sluigi * 747117328Sluigi * However, sometimes this ancestor requirement is inconvenient -- 748117328Sluigi * sometimes it's necessary to create a sub pool where the sub pool is 749117328Sluigi * guaranteed to have the same lifetime as the parent pool. This is a 750117577Sluigi * guarantee implemented by the *caller*, not by the pool code. That 75198943Sluigi * is, the caller guarantees they won't destroy the sub pool 752117328Sluigi * individually prior to destroying the parent pool. 75398943Sluigi * 75498943Sluigi * In this case the caller must call apr_pool_join() to indicate this 75598943Sluigi * guarantee to the APR_POOL_DEBUG code. 75698943Sluigi * 75798943Sluigi * These functions are only implemented when #APR_POOL_DEBUG is set. 758117328Sluigi * 75998943Sluigi * @{ 760117328Sluigi */ 76198943Sluigi#if APR_POOL_DEBUG || defined(DOXYGEN) 76298943Sluigi/** 76398943Sluigi * Guarantee that a subpool has the same lifetime as the parent. 764117328Sluigi * @param p The parent pool 765117328Sluigi * @param sub The subpool 766117328Sluigi */ 76798943SluigiAPR_DECLARE(void) apr_pool_join(apr_pool_t *p, apr_pool_t *sub) 76898943Sluigi __attribute__((nonnull(2))); 76998943Sluigi 77098943Sluigi/** 77198943Sluigi * Find a pool from something allocated in it. 77298943Sluigi * @param mem The thing allocated in the pool 773117577Sluigi * @return The pool it is allocated in 77498943Sluigi */ 77598943SluigiAPR_DECLARE(apr_pool_t *) apr_pool_find(const void *mem); 77698943Sluigi 77798943Sluigi/** 77898943Sluigi * Report the number of bytes currently in the pool 77998943Sluigi * @param p The pool to inspect 78098943Sluigi * @param recurse Recurse/include the subpools' sizes 78198943Sluigi * @return The number of bytes 78298943Sluigi */ 78398943SluigiAPR_DECLARE(apr_size_t) apr_pool_num_bytes(apr_pool_t *p, int recurse) 78498943Sluigi __attribute__((nonnull(1))); 78598943Sluigi 78698943Sluigi/** 78798943Sluigi * Lock a pool 78898943Sluigi * @param pool The pool to lock 78998943Sluigi * @param flag The flag 79098943Sluigi */ 79199475SluigiAPR_DECLARE(void) apr_pool_lock(apr_pool_t *pool, int flag); 79299475Sluigi 79399475Sluigi/* @} */ 794117328Sluigi 79598943Sluigi#else /* APR_POOL_DEBUG or DOXYGEN */ 79699475Sluigi 79799475Sluigi#ifdef apr_pool_join 79899475Sluigi#undef apr_pool_join 79999475Sluigi#endif 80099475Sluigi#define apr_pool_join(a,b) 80199475Sluigi 80299475Sluigi#ifdef apr_pool_lock 80399475Sluigi#undef apr_pool_lock 80499475Sluigi#endif 80599475Sluigi#define apr_pool_lock(pool, lock) 80699475Sluigi 80799475Sluigi#endif /* APR_POOL_DEBUG or DOXYGEN */ 80899475Sluigi 80999475Sluigi/** @} */ 81099475Sluigi 81199475Sluigi#ifdef __cplusplus 81299475Sluigi} 81399475Sluigi#endif 81499475Sluigi 81599475Sluigi#endif /* !APR_POOLS_H */ 81699475Sluigi