apr_pools.h revision 253734
1251875Speter/* Licensed to the Apache Software Foundation (ASF) under one or more 2251875Speter * contributor license agreements. See the NOTICE file distributed with 3251875Speter * this work for additional information regarding copyright ownership. 4251875Speter * The ASF licenses this file to You under the Apache License, Version 2.0 5251875Speter * (the "License"); you may not use this file except in compliance with 6251875Speter * the License. You may obtain a copy of the License at 7251875Speter * 8251875Speter * http://www.apache.org/licenses/LICENSE-2.0 9251875Speter * 10251875Speter * Unless required by applicable law or agreed to in writing, software 11251875Speter * distributed under the License is distributed on an "AS IS" BASIS, 12251875Speter * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13251875Speter * See the License for the specific language governing permissions and 14251875Speter * limitations under the License. 15251875Speter */ 16251875Speter 17251875Speter#ifndef APR_POOLS_H 18251875Speter#define APR_POOLS_H 19251875Speter 20251875Speter/** 21251875Speter * @file apr_pools.h 22251875Speter * @brief APR memory allocation 23251875Speter * 24251875Speter * Resource allocation routines... 25251875Speter * 26251875Speter * designed so that we don't have to keep track of EVERYTHING so that 27251875Speter * it can be explicitly freed later (a fundamentally unsound strategy --- 28251875Speter * particularly in the presence of die()). 29251875Speter * 30251875Speter * Instead, we maintain pools, and allocate items (both memory and I/O 31251875Speter * handlers) from the pools --- currently there are two, one for 32251875Speter * per-transaction info, and one for config info. When a transaction is 33251875Speter * over, we can delete everything in the per-transaction apr_pool_t without 34251875Speter * fear, and without thinking too hard about it either. 35251875Speter * 36251875Speter * Note that most operations on pools are not thread-safe: a single pool 37251875Speter * should only be accessed by a single thread at any given time. The one 38251875Speter * exception to this rule is creating a subpool of a given pool: one or more 39251875Speter * threads can safely create subpools at the same time that another thread 40251875Speter * accesses the parent pool. 41251875Speter */ 42251875Speter 43251875Speter#include "apr.h" 44251875Speter#include "apr_errno.h" 45251875Speter#include "apr_general.h" /* for APR_STRINGIFY */ 46251875Speter#define APR_WANT_MEMFUNC /**< for no good reason? */ 47251875Speter#include "apr_want.h" 48251875Speter 49251875Speter#ifdef __cplusplus 50251875Speterextern "C" { 51251875Speter#endif 52251875Speter 53251875Speter/** 54251875Speter * @defgroup apr_pools Memory Pool Functions 55251875Speter * @ingroup APR 56251875Speter * @{ 57251875Speter */ 58251875Speter 59251875Speter/** The fundamental pool type */ 60251875Spetertypedef struct apr_pool_t apr_pool_t; 61251875Speter 62251875Speter 63251875Speter/** 64251875Speter * Declaration helper macro to construct apr_foo_pool_get()s. 65251875Speter * 66251875Speter * This standardized macro is used by opaque (APR) data types to return 67251875Speter * the apr_pool_t that is associated with the data type. 68251875Speter * 69251875Speter * APR_POOL_DECLARE_ACCESSOR() is used in a header file to declare the 70251875Speter * accessor function. A typical usage and result would be: 71251875Speter * <pre> 72251875Speter * APR_POOL_DECLARE_ACCESSOR(file); 73251875Speter * becomes: 74251875Speter * APR_DECLARE(apr_pool_t *) apr_file_pool_get(apr_file_t *ob); 75251875Speter * </pre> 76251875Speter * @remark Doxygen unwraps this macro (via doxygen.conf) to provide 77251875Speter * actual help for each specific occurance of apr_foo_pool_get. 78251875Speter * @remark the linkage is specified for APR. It would be possible to expand 79251875Speter * the macros to support other linkages. 80251875Speter */ 81251875Speter#define APR_POOL_DECLARE_ACCESSOR(type) \ 82251875Speter APR_DECLARE(apr_pool_t *) apr_##type##_pool_get \ 83251875Speter (const apr_##type##_t *the##type) 84251875Speter 85251875Speter/** 86251875Speter * Implementation helper macro to provide apr_foo_pool_get()s. 87251875Speter * 88251875Speter * In the implementation, the APR_POOL_IMPLEMENT_ACCESSOR() is used to 89251875Speter * actually define the function. It assumes the field is named "pool". 90251875Speter */ 91251875Speter#define APR_POOL_IMPLEMENT_ACCESSOR(type) \ 92251875Speter APR_DECLARE(apr_pool_t *) apr_##type##_pool_get \ 93251875Speter (const apr_##type##_t *the##type) \ 94251875Speter { return the##type->pool; } 95251875Speter 96251875Speter 97251875Speter/** 98251875Speter * Pool debug levels 99251875Speter * 100251875Speter * <pre> 101251875Speter * | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 102251875Speter * --------------------------------- 103251875Speter * | | | | | | | | x | General debug code enabled (useful in 104251875Speter * combination with --with-efence). 105251875Speter * 106251875Speter * | | | | | | | x | | Verbose output on stderr (report 107251875Speter * CREATE, CLEAR, DESTROY). 108251875Speter * 109251875Speter * | | | | x | | | | | Verbose output on stderr (report 110251875Speter * PALLOC, PCALLOC). 111251875Speter * 112251875Speter * | | | | | | x | | | Lifetime checking. On each use of a 113251875Speter * pool, check its lifetime. If the pool 114251875Speter * is out of scope, abort(). 115251875Speter * In combination with the verbose flag 116251875Speter * above, it will output LIFE in such an 117251875Speter * event prior to aborting. 118251875Speter * 119251875Speter * | | | | | x | | | | Pool owner checking. On each use of a 120251875Speter * pool, check if the current thread is the 121251875Speter * pools owner. If not, abort(). In 122251875Speter * combination with the verbose flag above, 123251875Speter * it will output OWNER in such an event 124251875Speter * prior to aborting. Use the debug 125251875Speter * function apr_pool_owner_set() to switch 126251875Speter * a pools ownership. 127251875Speter * 128251875Speter * When no debug level was specified, assume general debug mode. 129251875Speter * If level 0 was specified, debugging is switched off 130251875Speter * </pre> 131251875Speter */ 132251875Speter#if defined(APR_POOL_DEBUG) 133251875Speter/* If APR_POOL_DEBUG is blank, we get 1; if it is a number, we get -1. */ 134251875Speter#if (APR_POOL_DEBUG - APR_POOL_DEBUG -1 == 1) 135251875Speter#undef APR_POOL_DEBUG 136251875Speter#define APR_POOL_DEBUG 1 137251875Speter#endif 138251875Speter#else 139251875Speter#define APR_POOL_DEBUG 0 140251875Speter#endif 141251875Speter 142251875Speter/** the place in the code where the particular function was called */ 143251875Speter#define APR_POOL__FILE_LINE__ __FILE__ ":" APR_STRINGIFY(__LINE__) 144251875Speter 145251875Speter 146251875Speter 147251875Speter/** A function that is called when allocation fails. */ 148251875Spetertypedef int (*apr_abortfunc_t)(int retcode); 149251875Speter 150251875Speter/* 151251875Speter * APR memory structure manipulators (pools, tables, and arrays). 152251875Speter */ 153251875Speter 154251875Speter/* 155251875Speter * Initialization 156251875Speter */ 157251875Speter 158251875Speter/** 159251875Speter * Setup all of the internal structures required to use pools 160251875Speter * @remark Programs do NOT need to call this directly. APR will call this 161251875Speter * automatically from apr_initialize. 162251875Speter * @internal 163251875Speter */ 164251875SpeterAPR_DECLARE(apr_status_t) apr_pool_initialize(void); 165251875Speter 166251875Speter/** 167251875Speter * Tear down all of the internal structures required to use pools 168251875Speter * @remark Programs do NOT need to call this directly. APR will call this 169251875Speter * automatically from apr_terminate. 170251875Speter * @internal 171251875Speter */ 172251875SpeterAPR_DECLARE(void) apr_pool_terminate(void); 173251875Speter 174251875Speter 175251875Speter/* 176251875Speter * Pool creation/destruction 177251875Speter */ 178251875Speter 179251875Speter#include "apr_allocator.h" 180251875Speter 181251875Speter/** 182251875Speter * Create a new pool. 183251875Speter * @param newpool The pool we have just created. 184251875Speter * @param parent The parent pool. If this is NULL, the new pool is a root 185251875Speter * pool. If it is non-NULL, the new pool will inherit all 186251875Speter * of its parent pool's attributes, except the apr_pool_t will 187251875Speter * be a sub-pool. 188251875Speter * @param abort_fn A function to use if the pool cannot allocate more memory. 189251875Speter * @param allocator The allocator to use with the new pool. If NULL the 190251875Speter * allocator of the parent pool will be used. 191251875Speter * @remark This function is thread-safe, in the sense that multiple threads 192251875Speter * can safely create subpools of the same parent pool concurrently. 193251875Speter * Similarly, a subpool can be created by one thread at the same 194251875Speter * time that another thread accesses the parent pool. 195251875Speter */ 196251875SpeterAPR_DECLARE(apr_status_t) apr_pool_create_ex(apr_pool_t **newpool, 197251875Speter apr_pool_t *parent, 198251875Speter apr_abortfunc_t abort_fn, 199253734Speter apr_allocator_t *allocator) 200253734Speter __attribute__((nonnull(1))); 201251875Speter 202251875Speter/** 203251875Speter * Create a new pool. 204251875Speter * @deprecated @see apr_pool_create_unmanaged_ex. 205251875Speter */ 206251875SpeterAPR_DECLARE(apr_status_t) apr_pool_create_core_ex(apr_pool_t **newpool, 207251875Speter apr_abortfunc_t abort_fn, 208251875Speter apr_allocator_t *allocator); 209251875Speter 210251875Speter/** 211251875Speter * Create a new unmanaged pool. 212251875Speter * @param newpool The pool we have just created. 213251875Speter * @param abort_fn A function to use if the pool cannot allocate more memory. 214251875Speter * @param allocator The allocator to use with the new pool. If NULL a 215251875Speter * new allocator will be crated with newpool as owner. 216251875Speter * @remark An unmanaged pool is a special pool without a parent; it will 217251875Speter * NOT be destroyed upon apr_terminate. It must be explicitly 218251875Speter * destroyed by calling apr_pool_destroy, to prevent memory leaks. 219251875Speter * Use of this function is discouraged, think twice about whether 220251875Speter * you really really need it. 221251875Speter */ 222251875SpeterAPR_DECLARE(apr_status_t) apr_pool_create_unmanaged_ex(apr_pool_t **newpool, 223251875Speter apr_abortfunc_t abort_fn, 224253734Speter apr_allocator_t *allocator) 225253734Speter __attribute__((nonnull(1))); 226251875Speter 227251875Speter/** 228251875Speter * Debug version of apr_pool_create_ex. 229251875Speter * @param newpool @see apr_pool_create. 230251875Speter * @param parent @see apr_pool_create. 231251875Speter * @param abort_fn @see apr_pool_create. 232251875Speter * @param allocator @see apr_pool_create. 233251875Speter * @param file_line Where the function is called from. 234251875Speter * This is usually APR_POOL__FILE_LINE__. 235251875Speter * @remark Only available when APR_POOL_DEBUG is defined. 236251875Speter * Call this directly if you have you apr_pool_create_ex 237251875Speter * calls in a wrapper function and wish to override 238251875Speter * the file_line argument to reflect the caller of 239251875Speter * your wrapper function. If you do not have 240251875Speter * apr_pool_create_ex in a wrapper, trust the macro 241251875Speter * and don't call apr_pool_create_ex_debug directly. 242251875Speter */ 243251875SpeterAPR_DECLARE(apr_status_t) apr_pool_create_ex_debug(apr_pool_t **newpool, 244251875Speter apr_pool_t *parent, 245251875Speter apr_abortfunc_t abort_fn, 246251875Speter apr_allocator_t *allocator, 247253734Speter const char *file_line) 248253734Speter __attribute__((nonnull(1))); 249251875Speter 250251875Speter#if APR_POOL_DEBUG 251251875Speter#define apr_pool_create_ex(newpool, parent, abort_fn, allocator) \ 252251875Speter apr_pool_create_ex_debug(newpool, parent, abort_fn, allocator, \ 253251875Speter APR_POOL__FILE_LINE__) 254251875Speter#endif 255251875Speter 256251875Speter/** 257251875Speter * Debug version of apr_pool_create_core_ex. 258251875Speter * @deprecated @see apr_pool_create_unmanaged_ex_debug. 259251875Speter */ 260251875SpeterAPR_DECLARE(apr_status_t) apr_pool_create_core_ex_debug(apr_pool_t **newpool, 261251875Speter apr_abortfunc_t abort_fn, 262251875Speter apr_allocator_t *allocator, 263251875Speter const char *file_line); 264251875Speter 265251875Speter/** 266251875Speter * Debug version of apr_pool_create_unmanaged_ex. 267251875Speter * @param newpool @see apr_pool_create_unmanaged. 268251875Speter * @param abort_fn @see apr_pool_create_unmanaged. 269251875Speter * @param allocator @see apr_pool_create_unmanaged. 270251875Speter * @param file_line Where the function is called from. 271251875Speter * This is usually APR_POOL__FILE_LINE__. 272251875Speter * @remark Only available when APR_POOL_DEBUG is defined. 273251875Speter * Call this directly if you have you apr_pool_create_unmanaged_ex 274251875Speter * calls in a wrapper function and wish to override 275251875Speter * the file_line argument to reflect the caller of 276251875Speter * your wrapper function. If you do not have 277251875Speter * apr_pool_create_core_ex in a wrapper, trust the macro 278251875Speter * and don't call apr_pool_create_core_ex_debug directly. 279251875Speter */ 280251875SpeterAPR_DECLARE(apr_status_t) apr_pool_create_unmanaged_ex_debug(apr_pool_t **newpool, 281251875Speter apr_abortfunc_t abort_fn, 282251875Speter apr_allocator_t *allocator, 283253734Speter const char *file_line) 284253734Speter __attribute__((nonnull(1))); 285251875Speter 286251875Speter#if APR_POOL_DEBUG 287251875Speter#define apr_pool_create_core_ex(newpool, abort_fn, allocator) \ 288251875Speter apr_pool_create_unmanaged_ex_debug(newpool, abort_fn, allocator, \ 289251875Speter APR_POOL__FILE_LINE__) 290251875Speter 291251875Speter#define apr_pool_create_unmanaged_ex(newpool, abort_fn, allocator) \ 292251875Speter apr_pool_create_unmanaged_ex_debug(newpool, abort_fn, allocator, \ 293251875Speter APR_POOL__FILE_LINE__) 294251875Speter 295251875Speter#endif 296251875Speter 297251875Speter/** 298251875Speter * Create a new pool. 299251875Speter * @param newpool The pool we have just created. 300251875Speter * @param parent The parent pool. If this is NULL, the new pool is a root 301251875Speter * pool. If it is non-NULL, the new pool will inherit all 302251875Speter * of its parent pool's attributes, except the apr_pool_t will 303251875Speter * be a sub-pool. 304251875Speter * @remark This function is thread-safe, in the sense that multiple threads 305251875Speter * can safely create subpools of the same parent pool concurrently. 306251875Speter * Similarly, a subpool can be created by one thread at the same 307251875Speter * time that another thread accesses the parent pool. 308251875Speter */ 309251875Speter#if defined(DOXYGEN) 310251875SpeterAPR_DECLARE(apr_status_t) apr_pool_create(apr_pool_t **newpool, 311251875Speter apr_pool_t *parent); 312251875Speter#else 313251875Speter#if APR_POOL_DEBUG 314251875Speter#define apr_pool_create(newpool, parent) \ 315251875Speter apr_pool_create_ex_debug(newpool, parent, NULL, NULL, \ 316251875Speter APR_POOL__FILE_LINE__) 317251875Speter#else 318251875Speter#define apr_pool_create(newpool, parent) \ 319251875Speter apr_pool_create_ex(newpool, parent, NULL, NULL) 320251875Speter#endif 321251875Speter#endif 322251875Speter 323251875Speter/** 324251875Speter * Create a new pool. 325251875Speter * @param newpool The pool we have just created. 326251875Speter */ 327251875Speter#if defined(DOXYGEN) 328251875SpeterAPR_DECLARE(apr_status_t) apr_pool_create_core(apr_pool_t **newpool); 329251875SpeterAPR_DECLARE(apr_status_t) apr_pool_create_unmanaged(apr_pool_t **newpool); 330251875Speter#else 331251875Speter#if APR_POOL_DEBUG 332251875Speter#define apr_pool_create_core(newpool) \ 333251875Speter apr_pool_create_unmanaged_ex_debug(newpool, NULL, NULL, \ 334251875Speter APR_POOL__FILE_LINE__) 335251875Speter#define apr_pool_create_unmanaged(newpool) \ 336251875Speter apr_pool_create_unmanaged_ex_debug(newpool, NULL, NULL, \ 337251875Speter APR_POOL__FILE_LINE__) 338251875Speter#else 339251875Speter#define apr_pool_create_core(newpool) \ 340251875Speter apr_pool_create_unmanaged_ex(newpool, NULL, NULL) 341251875Speter#define apr_pool_create_unmanaged(newpool) \ 342251875Speter apr_pool_create_unmanaged_ex(newpool, NULL, NULL) 343251875Speter#endif 344251875Speter#endif 345251875Speter 346251875Speter/** 347251875Speter * Find the pool's allocator 348251875Speter * @param pool The pool to get the allocator from. 349251875Speter */ 350253734SpeterAPR_DECLARE(apr_allocator_t *) apr_pool_allocator_get(apr_pool_t *pool) 351253734Speter __attribute__((nonnull(1))); 352251875Speter 353251875Speter/** 354251875Speter * Clear all memory in the pool and run all the cleanups. This also destroys all 355251875Speter * subpools. 356251875Speter * @param p The pool to clear 357251875Speter * @remark This does not actually free the memory, it just allows the pool 358251875Speter * to re-use this memory for the next allocation. 359251875Speter * @see apr_pool_destroy() 360251875Speter */ 361253734SpeterAPR_DECLARE(void) apr_pool_clear(apr_pool_t *p) __attribute__((nonnull(1))); 362251875Speter 363251875Speter/** 364251875Speter * Debug version of apr_pool_clear. 365251875Speter * @param p See: apr_pool_clear. 366251875Speter * @param file_line Where the function is called from. 367251875Speter * This is usually APR_POOL__FILE_LINE__. 368251875Speter * @remark Only available when APR_POOL_DEBUG is defined. 369251875Speter * Call this directly if you have you apr_pool_clear 370251875Speter * calls in a wrapper function and wish to override 371251875Speter * the file_line argument to reflect the caller of 372251875Speter * your wrapper function. If you do not have 373251875Speter * apr_pool_clear in a wrapper, trust the macro 374251875Speter * and don't call apr_pool_destroy_clear directly. 375251875Speter */ 376251875SpeterAPR_DECLARE(void) apr_pool_clear_debug(apr_pool_t *p, 377253734Speter const char *file_line) 378253734Speter __attribute__((nonnull(1))); 379251875Speter 380251875Speter#if APR_POOL_DEBUG 381251875Speter#define apr_pool_clear(p) \ 382251875Speter apr_pool_clear_debug(p, APR_POOL__FILE_LINE__) 383251875Speter#endif 384251875Speter 385251875Speter/** 386251875Speter * Destroy the pool. This takes similar action as apr_pool_clear() and then 387251875Speter * frees all the memory. 388251875Speter * @param p The pool to destroy 389251875Speter * @remark This will actually free the memory 390251875Speter */ 391253734SpeterAPR_DECLARE(void) apr_pool_destroy(apr_pool_t *p) __attribute__((nonnull(1))); 392251875Speter 393251875Speter/** 394251875Speter * Debug version of apr_pool_destroy. 395251875Speter * @param p See: apr_pool_destroy. 396251875Speter * @param file_line Where the function is called from. 397251875Speter * This is usually APR_POOL__FILE_LINE__. 398251875Speter * @remark Only available when APR_POOL_DEBUG is defined. 399251875Speter * Call this directly if you have you apr_pool_destroy 400251875Speter * calls in a wrapper function and wish to override 401251875Speter * the file_line argument to reflect the caller of 402251875Speter * your wrapper function. If you do not have 403251875Speter * apr_pool_destroy in a wrapper, trust the macro 404251875Speter * and don't call apr_pool_destroy_debug directly. 405251875Speter */ 406251875SpeterAPR_DECLARE(void) apr_pool_destroy_debug(apr_pool_t *p, 407253734Speter const char *file_line) 408253734Speter __attribute__((nonnull(1))); 409251875Speter 410251875Speter#if APR_POOL_DEBUG 411251875Speter#define apr_pool_destroy(p) \ 412251875Speter apr_pool_destroy_debug(p, APR_POOL__FILE_LINE__) 413251875Speter#endif 414251875Speter 415251875Speter 416251875Speter/* 417251875Speter * Memory allocation 418251875Speter */ 419251875Speter 420251875Speter/** 421251875Speter * Allocate a block of memory from a pool 422251875Speter * @param p The pool to allocate from 423251875Speter * @param size The amount of memory to allocate 424251875Speter * @return The allocated memory 425251875Speter */ 426253734SpeterAPR_DECLARE(void *) apr_palloc(apr_pool_t *p, apr_size_t size) 427253734Speter#if defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4)) 428253734Speter __attribute__((alloc_size(2))) 429253734Speter#endif 430253734Speter __attribute__((nonnull(1))); 431251875Speter 432251875Speter/** 433251875Speter * Debug version of apr_palloc 434251875Speter * @param p See: apr_palloc 435251875Speter * @param size See: apr_palloc 436251875Speter * @param file_line Where the function is called from. 437251875Speter * This is usually APR_POOL__FILE_LINE__. 438251875Speter * @return See: apr_palloc 439251875Speter */ 440251875SpeterAPR_DECLARE(void *) apr_palloc_debug(apr_pool_t *p, apr_size_t size, 441253734Speter const char *file_line) 442253734Speter#if defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4)) 443253734Speter __attribute__((alloc_size(2))) 444253734Speter#endif 445253734Speter __attribute__((nonnull(1))); 446251875Speter 447251875Speter#if APR_POOL_DEBUG 448251875Speter#define apr_palloc(p, size) \ 449251875Speter apr_palloc_debug(p, size, APR_POOL__FILE_LINE__) 450251875Speter#endif 451251875Speter 452251875Speter/** 453251875Speter * Allocate a block of memory from a pool and set all of the memory to 0 454251875Speter * @param p The pool to allocate from 455251875Speter * @param size The amount of memory to allocate 456251875Speter * @return The allocated memory 457251875Speter */ 458251875Speter#if defined(DOXYGEN) 459251875SpeterAPR_DECLARE(void *) apr_pcalloc(apr_pool_t *p, apr_size_t size); 460251875Speter#elif !APR_POOL_DEBUG 461251875Speter#define apr_pcalloc(p, size) memset(apr_palloc(p, size), 0, size) 462251875Speter#endif 463251875Speter 464251875Speter/** 465251875Speter * Debug version of apr_pcalloc 466251875Speter * @param p See: apr_pcalloc 467251875Speter * @param size See: apr_pcalloc 468251875Speter * @param file_line Where the function is called from. 469251875Speter * This is usually APR_POOL__FILE_LINE__. 470251875Speter * @return See: apr_pcalloc 471251875Speter */ 472251875SpeterAPR_DECLARE(void *) apr_pcalloc_debug(apr_pool_t *p, apr_size_t size, 473253734Speter const char *file_line) 474253734Speter __attribute__((nonnull(1))); 475251875Speter 476251875Speter#if APR_POOL_DEBUG 477251875Speter#define apr_pcalloc(p, size) \ 478251875Speter apr_pcalloc_debug(p, size, APR_POOL__FILE_LINE__) 479251875Speter#endif 480251875Speter 481251875Speter 482251875Speter/* 483251875Speter * Pool Properties 484251875Speter */ 485251875Speter 486251875Speter/** 487251875Speter * Set the function to be called when an allocation failure occurs. 488251875Speter * @remark If the program wants APR to exit on a memory allocation error, 489251875Speter * then this function can be called to set the callback to use (for 490251875Speter * performing cleanup and then exiting). If this function is not called, 491251875Speter * then APR will return an error and expect the calling program to 492251875Speter * deal with the error accordingly. 493251875Speter */ 494251875SpeterAPR_DECLARE(void) apr_pool_abort_set(apr_abortfunc_t abortfunc, 495253734Speter apr_pool_t *pool) 496253734Speter __attribute__((nonnull(2))); 497251875Speter 498251875Speter/** 499251875Speter * Get the abort function associated with the specified pool. 500251875Speter * @param pool The pool for retrieving the abort function. 501251875Speter * @return The abort function for the given pool. 502251875Speter */ 503253734SpeterAPR_DECLARE(apr_abortfunc_t) apr_pool_abort_get(apr_pool_t *pool) 504253734Speter __attribute__((nonnull(1))); 505251875Speter 506251875Speter/** 507251875Speter * Get the parent pool of the specified pool. 508251875Speter * @param pool The pool for retrieving the parent pool. 509251875Speter * @return The parent of the given pool. 510251875Speter */ 511253734SpeterAPR_DECLARE(apr_pool_t *) apr_pool_parent_get(apr_pool_t *pool) 512253734Speter __attribute__((nonnull(1))); 513251875Speter 514251875Speter/** 515251875Speter * Determine if pool a is an ancestor of pool b. 516251875Speter * @param a The pool to search 517251875Speter * @param b The pool to search for 518251875Speter * @return True if a is an ancestor of b, NULL is considered an ancestor 519251875Speter * of all pools. 520251875Speter * @remark if compiled with APR_POOL_DEBUG, this function will also 521251875Speter * return true if A is a pool which has been guaranteed by the caller 522251875Speter * (using apr_pool_join) to have a lifetime at least as long as some 523251875Speter * ancestor of pool B. 524251875Speter */ 525251875SpeterAPR_DECLARE(int) apr_pool_is_ancestor(apr_pool_t *a, apr_pool_t *b); 526251875Speter 527251875Speter/** 528251875Speter * Tag a pool (give it a name) 529251875Speter * @param pool The pool to tag 530251875Speter * @param tag The tag 531251875Speter */ 532253734SpeterAPR_DECLARE(void) apr_pool_tag(apr_pool_t *pool, const char *tag) 533253734Speter __attribute__((nonnull(1))); 534251875Speter 535251875Speter 536251875Speter/* 537251875Speter * User data management 538251875Speter */ 539251875Speter 540251875Speter/** 541251875Speter * Set the data associated with the current pool 542251875Speter * @param data The user data associated with the pool. 543251875Speter * @param key The key to use for association 544251875Speter * @param cleanup The cleanup program to use to cleanup the data (NULL if none) 545251875Speter * @param pool The current pool 546251875Speter * @warning The data to be attached to the pool should have a life span 547251875Speter * at least as long as the pool it is being attached to. 548251875Speter * 549251875Speter * Users of APR must take EXTREME care when choosing a key to 550251875Speter * use for their data. It is possible to accidentally overwrite 551251875Speter * data by choosing a key that another part of the program is using. 552251875Speter * Therefore it is advised that steps are taken to ensure that unique 553251875Speter * keys are used for all of the userdata objects in a particular pool 554251875Speter * (the same key in two different pools or a pool and one of its 555251875Speter * subpools is okay) at all times. Careful namespace prefixing of 556251875Speter * key names is a typical way to help ensure this uniqueness. 557251875Speter * 558251875Speter */ 559253734SpeterAPR_DECLARE(apr_status_t) apr_pool_userdata_set(const void *data, 560253734Speter const char *key, 561253734Speter apr_status_t (*cleanup)(void *), 562253734Speter apr_pool_t *pool) 563253734Speter __attribute__((nonnull(2,4))); 564251875Speter 565251875Speter/** 566251875Speter * Set the data associated with the current pool 567251875Speter * @param data The user data associated with the pool. 568251875Speter * @param key The key to use for association 569251875Speter * @param cleanup The cleanup program to use to cleanup the data (NULL if none) 570251875Speter * @param pool The current pool 571251875Speter * @note same as apr_pool_userdata_set(), except that this version doesn't 572251875Speter * make a copy of the key (this function is useful, for example, when 573251875Speter * the key is a string literal) 574251875Speter * @warning This should NOT be used if the key could change addresses by 575251875Speter * any means between the apr_pool_userdata_setn() call and a 576251875Speter * subsequent apr_pool_userdata_get() on that key, such as if a 577251875Speter * static string is used as a userdata key in a DSO and the DSO could 578251875Speter * be unloaded and reloaded between the _setn() and the _get(). You 579251875Speter * MUST use apr_pool_userdata_set() in such cases. 580251875Speter * @warning More generally, the key and the data to be attached to the 581251875Speter * pool should have a life span at least as long as the pool itself. 582251875Speter * 583251875Speter */ 584251875SpeterAPR_DECLARE(apr_status_t) apr_pool_userdata_setn( 585253734Speter const void *data, const char *key, 586253734Speter apr_status_t (*cleanup)(void *), 587253734Speter apr_pool_t *pool) 588253734Speter __attribute__((nonnull(2,4))); 589251875Speter 590251875Speter/** 591251875Speter * Return the data associated with the current pool. 592251875Speter * @param data The user data associated with the pool. 593251875Speter * @param key The key for the data to retrieve 594251875Speter * @param pool The current pool. 595251875Speter */ 596251875SpeterAPR_DECLARE(apr_status_t) apr_pool_userdata_get(void **data, const char *key, 597253734Speter apr_pool_t *pool) 598253734Speter __attribute__((nonnull(1,2,3))); 599251875Speter 600251875Speter 601251875Speter/** 602251875Speter * @defgroup PoolCleanup Pool Cleanup Functions 603251875Speter * 604251875Speter * Cleanups are performed in the reverse order they were registered. That is: 605251875Speter * Last In, First Out. A cleanup function can safely allocate memory from 606251875Speter * the pool that is being cleaned up. It can also safely register additional 607251875Speter * cleanups which will be run LIFO, directly after the current cleanup 608251875Speter * terminates. Cleanups have to take caution in calling functions that 609251875Speter * create subpools. Subpools, created during cleanup will NOT automatically 610251875Speter * be cleaned up. In other words, cleanups are to clean up after themselves. 611251875Speter * 612251875Speter * @{ 613251875Speter */ 614251875Speter 615251875Speter/** 616251875Speter * Register a function to be called when a pool is cleared or destroyed 617251875Speter * @param p The pool register the cleanup with 618251875Speter * @param data The data to pass to the cleanup function. 619251875Speter * @param plain_cleanup The function to call when the pool is cleared 620251875Speter * or destroyed 621251875Speter * @param child_cleanup The function to call when a child process is about 622251875Speter * to exec - this function is called in the child, obviously! 623251875Speter */ 624251875SpeterAPR_DECLARE(void) apr_pool_cleanup_register( 625253734Speter apr_pool_t *p, const void *data, 626253734Speter apr_status_t (*plain_cleanup)(void *), 627253734Speter apr_status_t (*child_cleanup)(void *)) 628253734Speter __attribute__((nonnull(3,4))); 629251875Speter 630251875Speter/** 631251875Speter * Register a function to be called when a pool is cleared or destroyed. 632251875Speter * 633251875Speter * Unlike apr_pool_cleanup_register which register a cleanup 634251875Speter * that is called AFTER all subpools are destroyed this function register 635251875Speter * a function that will be called before any of the subpool is destoryed. 636251875Speter * 637251875Speter * @param p The pool register the cleanup with 638251875Speter * @param data The data to pass to the cleanup function. 639251875Speter * @param plain_cleanup The function to call when the pool is cleared 640251875Speter * or destroyed 641251875Speter */ 642251875SpeterAPR_DECLARE(void) apr_pool_pre_cleanup_register( 643253734Speter apr_pool_t *p, const void *data, 644253734Speter apr_status_t (*plain_cleanup)(void *)) 645253734Speter __attribute__((nonnull(3))); 646251875Speter 647251875Speter/** 648251875Speter * Remove a previously registered cleanup function. 649251875Speter * 650251875Speter * The cleanup most recently registered with @a p having the same values of 651251875Speter * @a data and @a cleanup will be removed. 652251875Speter * 653251875Speter * @param p The pool to remove the cleanup from 654251875Speter * @param data The data of the registered cleanup 655251875Speter * @param cleanup The function to remove from cleanup 656251875Speter * @remarks For some strange reason only the plain_cleanup is handled by this 657251875Speter * function 658251875Speter */ 659251875SpeterAPR_DECLARE(void) apr_pool_cleanup_kill(apr_pool_t *p, const void *data, 660253734Speter apr_status_t (*cleanup)(void *)) 661253734Speter __attribute__((nonnull(3))); 662251875Speter 663251875Speter/** 664251875Speter * Replace the child cleanup function of a previously registered cleanup. 665251875Speter * 666251875Speter * The cleanup most recently registered with @a p having the same values of 667251875Speter * @a data and @a plain_cleanup will have the registered child cleanup 668251875Speter * function replaced with @a child_cleanup. 669251875Speter * 670251875Speter * @param p The pool of the registered cleanup 671251875Speter * @param data The data of the registered cleanup 672251875Speter * @param plain_cleanup The plain cleanup function of the registered cleanup 673251875Speter * @param child_cleanup The function to register as the child cleanup 674251875Speter */ 675251875SpeterAPR_DECLARE(void) apr_pool_child_cleanup_set( 676253734Speter apr_pool_t *p, const void *data, 677253734Speter apr_status_t (*plain_cleanup)(void *), 678253734Speter apr_status_t (*child_cleanup)(void *)) 679253734Speter __attribute__((nonnull(3,4))); 680251875Speter 681251875Speter/** 682251875Speter * Run the specified cleanup function immediately and unregister it. 683251875Speter * 684251875Speter * The cleanup most recently registered with @a p having the same values of 685251875Speter * @a data and @a cleanup will be removed and @a cleanup will be called 686251875Speter * with @a data as the argument. 687251875Speter * 688251875Speter * @param p The pool to remove the cleanup from 689251875Speter * @param data The data to remove from cleanup 690251875Speter * @param cleanup The function to remove from cleanup 691251875Speter */ 692253734SpeterAPR_DECLARE(apr_status_t) apr_pool_cleanup_run(apr_pool_t *p, void *data, 693253734Speter apr_status_t (*cleanup)(void *)) 694253734Speter __attribute__((nonnull(3))); 695251875Speter 696251875Speter/** 697251875Speter * An empty cleanup function. 698251875Speter * 699251875Speter * Passed to apr_pool_cleanup_register() when no cleanup is required. 700251875Speter * 701251875Speter * @param data The data to cleanup, will not be used by this function. 702251875Speter */ 703251875SpeterAPR_DECLARE_NONSTD(apr_status_t) apr_pool_cleanup_null(void *data); 704251875Speter 705251875Speter/** 706251875Speter * Run all registered child cleanups, in preparation for an exec() 707251875Speter * call in a forked child -- close files, etc., but *don't* flush I/O 708251875Speter * buffers, *don't* wait for subprocesses, and *don't* free any 709251875Speter * memory. 710251875Speter */ 711251875SpeterAPR_DECLARE(void) apr_pool_cleanup_for_exec(void); 712251875Speter 713251875Speter/** @} */ 714251875Speter 715251875Speter/** 716251875Speter * @defgroup PoolDebug Pool Debugging functions. 717251875Speter * 718251875Speter * pools have nested lifetimes -- sub_pools are destroyed when the 719251875Speter * parent pool is cleared. We allow certain liberties with operations 720251875Speter * on things such as tables (and on other structures in a more general 721251875Speter * sense) where we allow the caller to insert values into a table which 722251875Speter * were not allocated from the table's pool. The table's data will 723251875Speter * remain valid as long as all the pools from which its values are 724251875Speter * allocated remain valid. 725251875Speter * 726251875Speter * For example, if B is a sub pool of A, and you build a table T in 727251875Speter * pool B, then it's safe to insert data allocated in A or B into T 728251875Speter * (because B lives at most as long as A does, and T is destroyed when 729251875Speter * B is cleared/destroyed). On the other hand, if S is a table in 730251875Speter * pool A, it is safe to insert data allocated in A into S, but it 731251875Speter * is *not safe* to insert data allocated from B into S... because 732251875Speter * B can be cleared/destroyed before A is (which would leave dangling 733251875Speter * pointers in T's data structures). 734251875Speter * 735251875Speter * In general we say that it is safe to insert data into a table T 736251875Speter * if the data is allocated in any ancestor of T's pool. This is the 737251875Speter * basis on which the APR_POOL_DEBUG code works -- it tests these ancestor 738251875Speter * relationships for all data inserted into tables. APR_POOL_DEBUG also 739251875Speter * provides tools (apr_pool_find, and apr_pool_is_ancestor) for other 740251875Speter * folks to implement similar restrictions for their own data 741251875Speter * structures. 742251875Speter * 743251875Speter * However, sometimes this ancestor requirement is inconvenient -- 744251875Speter * sometimes it's necessary to create a sub pool where the sub pool is 745251875Speter * guaranteed to have the same lifetime as the parent pool. This is a 746251875Speter * guarantee implemented by the *caller*, not by the pool code. That 747251875Speter * is, the caller guarantees they won't destroy the sub pool 748251875Speter * individually prior to destroying the parent pool. 749251875Speter * 750251875Speter * In this case the caller must call apr_pool_join() to indicate this 751251875Speter * guarantee to the APR_POOL_DEBUG code. 752251875Speter * 753251875Speter * These functions are only implemented when #APR_POOL_DEBUG is set. 754251875Speter * 755251875Speter * @{ 756251875Speter */ 757251875Speter#if APR_POOL_DEBUG || defined(DOXYGEN) 758251875Speter/** 759251875Speter * Guarantee that a subpool has the same lifetime as the parent. 760251875Speter * @param p The parent pool 761251875Speter * @param sub The subpool 762251875Speter */ 763253734SpeterAPR_DECLARE(void) apr_pool_join(apr_pool_t *p, apr_pool_t *sub) 764253734Speter __attribute__((nonnull(2))); 765251875Speter 766251875Speter/** 767251875Speter * Find a pool from something allocated in it. 768251875Speter * @param mem The thing allocated in the pool 769251875Speter * @return The pool it is allocated in 770251875Speter */ 771251875SpeterAPR_DECLARE(apr_pool_t *) apr_pool_find(const void *mem); 772251875Speter 773251875Speter/** 774251875Speter * Report the number of bytes currently in the pool 775251875Speter * @param p The pool to inspect 776251875Speter * @param recurse Recurse/include the subpools' sizes 777251875Speter * @return The number of bytes 778251875Speter */ 779253734SpeterAPR_DECLARE(apr_size_t) apr_pool_num_bytes(apr_pool_t *p, int recurse) 780253734Speter __attribute__((nonnull(1))); 781251875Speter 782251875Speter/** 783251875Speter * Lock a pool 784251875Speter * @param pool The pool to lock 785251875Speter * @param flag The flag 786251875Speter */ 787251875SpeterAPR_DECLARE(void) apr_pool_lock(apr_pool_t *pool, int flag); 788251875Speter 789251875Speter/* @} */ 790251875Speter 791251875Speter#else /* APR_POOL_DEBUG or DOXYGEN */ 792251875Speter 793251875Speter#ifdef apr_pool_join 794251875Speter#undef apr_pool_join 795251875Speter#endif 796251875Speter#define apr_pool_join(a,b) 797251875Speter 798251875Speter#ifdef apr_pool_lock 799251875Speter#undef apr_pool_lock 800251875Speter#endif 801251875Speter#define apr_pool_lock(pool, lock) 802251875Speter 803251875Speter#endif /* APR_POOL_DEBUG or DOXYGEN */ 804251875Speter 805251875Speter/** @} */ 806251875Speter 807251875Speter#ifdef __cplusplus 808251875Speter} 809251875Speter#endif 810251875Speter 811251875Speter#endif /* !APR_POOLS_H */ 812