apr_pools.h revision 251875
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, 199251875Speter apr_allocator_t *allocator); 200251875Speter 201251875Speter/** 202251875Speter * Create a new pool. 203251875Speter * @deprecated @see apr_pool_create_unmanaged_ex. 204251875Speter */ 205251875SpeterAPR_DECLARE(apr_status_t) apr_pool_create_core_ex(apr_pool_t **newpool, 206251875Speter apr_abortfunc_t abort_fn, 207251875Speter apr_allocator_t *allocator); 208251875Speter 209251875Speter/** 210251875Speter * Create a new unmanaged pool. 211251875Speter * @param newpool The pool we have just created. 212251875Speter * @param abort_fn A function to use if the pool cannot allocate more memory. 213251875Speter * @param allocator The allocator to use with the new pool. If NULL a 214251875Speter * new allocator will be crated with newpool as owner. 215251875Speter * @remark An unmanaged pool is a special pool without a parent; it will 216251875Speter * NOT be destroyed upon apr_terminate. It must be explicitly 217251875Speter * destroyed by calling apr_pool_destroy, to prevent memory leaks. 218251875Speter * Use of this function is discouraged, think twice about whether 219251875Speter * you really really need it. 220251875Speter */ 221251875SpeterAPR_DECLARE(apr_status_t) apr_pool_create_unmanaged_ex(apr_pool_t **newpool, 222251875Speter apr_abortfunc_t abort_fn, 223251875Speter apr_allocator_t *allocator); 224251875Speter 225251875Speter/** 226251875Speter * Debug version of apr_pool_create_ex. 227251875Speter * @param newpool @see apr_pool_create. 228251875Speter * @param parent @see apr_pool_create. 229251875Speter * @param abort_fn @see apr_pool_create. 230251875Speter * @param allocator @see apr_pool_create. 231251875Speter * @param file_line Where the function is called from. 232251875Speter * This is usually APR_POOL__FILE_LINE__. 233251875Speter * @remark Only available when APR_POOL_DEBUG is defined. 234251875Speter * Call this directly if you have you apr_pool_create_ex 235251875Speter * calls in a wrapper function and wish to override 236251875Speter * the file_line argument to reflect the caller of 237251875Speter * your wrapper function. If you do not have 238251875Speter * apr_pool_create_ex in a wrapper, trust the macro 239251875Speter * and don't call apr_pool_create_ex_debug directly. 240251875Speter */ 241251875SpeterAPR_DECLARE(apr_status_t) apr_pool_create_ex_debug(apr_pool_t **newpool, 242251875Speter apr_pool_t *parent, 243251875Speter apr_abortfunc_t abort_fn, 244251875Speter apr_allocator_t *allocator, 245251875Speter const char *file_line); 246251875Speter 247251875Speter#if APR_POOL_DEBUG 248251875Speter#define apr_pool_create_ex(newpool, parent, abort_fn, allocator) \ 249251875Speter apr_pool_create_ex_debug(newpool, parent, abort_fn, allocator, \ 250251875Speter APR_POOL__FILE_LINE__) 251251875Speter#endif 252251875Speter 253251875Speter/** 254251875Speter * Debug version of apr_pool_create_core_ex. 255251875Speter * @deprecated @see apr_pool_create_unmanaged_ex_debug. 256251875Speter */ 257251875SpeterAPR_DECLARE(apr_status_t) apr_pool_create_core_ex_debug(apr_pool_t **newpool, 258251875Speter apr_abortfunc_t abort_fn, 259251875Speter apr_allocator_t *allocator, 260251875Speter const char *file_line); 261251875Speter 262251875Speter/** 263251875Speter * Debug version of apr_pool_create_unmanaged_ex. 264251875Speter * @param newpool @see apr_pool_create_unmanaged. 265251875Speter * @param abort_fn @see apr_pool_create_unmanaged. 266251875Speter * @param allocator @see apr_pool_create_unmanaged. 267251875Speter * @param file_line Where the function is called from. 268251875Speter * This is usually APR_POOL__FILE_LINE__. 269251875Speter * @remark Only available when APR_POOL_DEBUG is defined. 270251875Speter * Call this directly if you have you apr_pool_create_unmanaged_ex 271251875Speter * calls in a wrapper function and wish to override 272251875Speter * the file_line argument to reflect the caller of 273251875Speter * your wrapper function. If you do not have 274251875Speter * apr_pool_create_core_ex in a wrapper, trust the macro 275251875Speter * and don't call apr_pool_create_core_ex_debug directly. 276251875Speter */ 277251875SpeterAPR_DECLARE(apr_status_t) apr_pool_create_unmanaged_ex_debug(apr_pool_t **newpool, 278251875Speter apr_abortfunc_t abort_fn, 279251875Speter apr_allocator_t *allocator, 280251875Speter const char *file_line); 281251875Speter 282251875Speter#if APR_POOL_DEBUG 283251875Speter#define apr_pool_create_core_ex(newpool, abort_fn, allocator) \ 284251875Speter apr_pool_create_unmanaged_ex_debug(newpool, abort_fn, allocator, \ 285251875Speter APR_POOL__FILE_LINE__) 286251875Speter 287251875Speter#define apr_pool_create_unmanaged_ex(newpool, abort_fn, allocator) \ 288251875Speter apr_pool_create_unmanaged_ex_debug(newpool, abort_fn, allocator, \ 289251875Speter APR_POOL__FILE_LINE__) 290251875Speter 291251875Speter#endif 292251875Speter 293251875Speter/** 294251875Speter * Create a new pool. 295251875Speter * @param newpool The pool we have just created. 296251875Speter * @param parent The parent pool. If this is NULL, the new pool is a root 297251875Speter * pool. If it is non-NULL, the new pool will inherit all 298251875Speter * of its parent pool's attributes, except the apr_pool_t will 299251875Speter * be a sub-pool. 300251875Speter * @remark This function is thread-safe, in the sense that multiple threads 301251875Speter * can safely create subpools of the same parent pool concurrently. 302251875Speter * Similarly, a subpool can be created by one thread at the same 303251875Speter * time that another thread accesses the parent pool. 304251875Speter */ 305251875Speter#if defined(DOXYGEN) 306251875SpeterAPR_DECLARE(apr_status_t) apr_pool_create(apr_pool_t **newpool, 307251875Speter apr_pool_t *parent); 308251875Speter#else 309251875Speter#if APR_POOL_DEBUG 310251875Speter#define apr_pool_create(newpool, parent) \ 311251875Speter apr_pool_create_ex_debug(newpool, parent, NULL, NULL, \ 312251875Speter APR_POOL__FILE_LINE__) 313251875Speter#else 314251875Speter#define apr_pool_create(newpool, parent) \ 315251875Speter apr_pool_create_ex(newpool, parent, NULL, NULL) 316251875Speter#endif 317251875Speter#endif 318251875Speter 319251875Speter/** 320251875Speter * Create a new pool. 321251875Speter * @param newpool The pool we have just created. 322251875Speter */ 323251875Speter#if defined(DOXYGEN) 324251875SpeterAPR_DECLARE(apr_status_t) apr_pool_create_core(apr_pool_t **newpool); 325251875SpeterAPR_DECLARE(apr_status_t) apr_pool_create_unmanaged(apr_pool_t **newpool); 326251875Speter#else 327251875Speter#if APR_POOL_DEBUG 328251875Speter#define apr_pool_create_core(newpool) \ 329251875Speter apr_pool_create_unmanaged_ex_debug(newpool, NULL, NULL, \ 330251875Speter APR_POOL__FILE_LINE__) 331251875Speter#define apr_pool_create_unmanaged(newpool) \ 332251875Speter apr_pool_create_unmanaged_ex_debug(newpool, NULL, NULL, \ 333251875Speter APR_POOL__FILE_LINE__) 334251875Speter#else 335251875Speter#define apr_pool_create_core(newpool) \ 336251875Speter apr_pool_create_unmanaged_ex(newpool, NULL, NULL) 337251875Speter#define apr_pool_create_unmanaged(newpool) \ 338251875Speter apr_pool_create_unmanaged_ex(newpool, NULL, NULL) 339251875Speter#endif 340251875Speter#endif 341251875Speter 342251875Speter/** 343251875Speter * Find the pool's allocator 344251875Speter * @param pool The pool to get the allocator from. 345251875Speter */ 346251875SpeterAPR_DECLARE(apr_allocator_t *) apr_pool_allocator_get(apr_pool_t *pool); 347251875Speter 348251875Speter/** 349251875Speter * Clear all memory in the pool and run all the cleanups. This also destroys all 350251875Speter * subpools. 351251875Speter * @param p The pool to clear 352251875Speter * @remark This does not actually free the memory, it just allows the pool 353251875Speter * to re-use this memory for the next allocation. 354251875Speter * @see apr_pool_destroy() 355251875Speter */ 356251875SpeterAPR_DECLARE(void) apr_pool_clear(apr_pool_t *p); 357251875Speter 358251875Speter/** 359251875Speter * Debug version of apr_pool_clear. 360251875Speter * @param p See: apr_pool_clear. 361251875Speter * @param file_line Where the function is called from. 362251875Speter * This is usually APR_POOL__FILE_LINE__. 363251875Speter * @remark Only available when APR_POOL_DEBUG is defined. 364251875Speter * Call this directly if you have you apr_pool_clear 365251875Speter * calls in a wrapper function and wish to override 366251875Speter * the file_line argument to reflect the caller of 367251875Speter * your wrapper function. If you do not have 368251875Speter * apr_pool_clear in a wrapper, trust the macro 369251875Speter * and don't call apr_pool_destroy_clear directly. 370251875Speter */ 371251875SpeterAPR_DECLARE(void) apr_pool_clear_debug(apr_pool_t *p, 372251875Speter const char *file_line); 373251875Speter 374251875Speter#if APR_POOL_DEBUG 375251875Speter#define apr_pool_clear(p) \ 376251875Speter apr_pool_clear_debug(p, APR_POOL__FILE_LINE__) 377251875Speter#endif 378251875Speter 379251875Speter/** 380251875Speter * Destroy the pool. This takes similar action as apr_pool_clear() and then 381251875Speter * frees all the memory. 382251875Speter * @param p The pool to destroy 383251875Speter * @remark This will actually free the memory 384251875Speter */ 385251875SpeterAPR_DECLARE(void) apr_pool_destroy(apr_pool_t *p); 386251875Speter 387251875Speter/** 388251875Speter * Debug version of apr_pool_destroy. 389251875Speter * @param p See: apr_pool_destroy. 390251875Speter * @param file_line Where the function is called from. 391251875Speter * This is usually APR_POOL__FILE_LINE__. 392251875Speter * @remark Only available when APR_POOL_DEBUG is defined. 393251875Speter * Call this directly if you have you apr_pool_destroy 394251875Speter * calls in a wrapper function and wish to override 395251875Speter * the file_line argument to reflect the caller of 396251875Speter * your wrapper function. If you do not have 397251875Speter * apr_pool_destroy in a wrapper, trust the macro 398251875Speter * and don't call apr_pool_destroy_debug directly. 399251875Speter */ 400251875SpeterAPR_DECLARE(void) apr_pool_destroy_debug(apr_pool_t *p, 401251875Speter const char *file_line); 402251875Speter 403251875Speter#if APR_POOL_DEBUG 404251875Speter#define apr_pool_destroy(p) \ 405251875Speter apr_pool_destroy_debug(p, APR_POOL__FILE_LINE__) 406251875Speter#endif 407251875Speter 408251875Speter 409251875Speter/* 410251875Speter * Memory allocation 411251875Speter */ 412251875Speter 413251875Speter/** 414251875Speter * Allocate a block of memory from a pool 415251875Speter * @param p The pool to allocate from 416251875Speter * @param size The amount of memory to allocate 417251875Speter * @return The allocated memory 418251875Speter */ 419251875SpeterAPR_DECLARE(void *) apr_palloc(apr_pool_t *p, apr_size_t size); 420251875Speter 421251875Speter/** 422251875Speter * Debug version of apr_palloc 423251875Speter * @param p See: apr_palloc 424251875Speter * @param size See: apr_palloc 425251875Speter * @param file_line Where the function is called from. 426251875Speter * This is usually APR_POOL__FILE_LINE__. 427251875Speter * @return See: apr_palloc 428251875Speter */ 429251875SpeterAPR_DECLARE(void *) apr_palloc_debug(apr_pool_t *p, apr_size_t size, 430251875Speter const char *file_line); 431251875Speter 432251875Speter#if APR_POOL_DEBUG 433251875Speter#define apr_palloc(p, size) \ 434251875Speter apr_palloc_debug(p, size, APR_POOL__FILE_LINE__) 435251875Speter#endif 436251875Speter 437251875Speter/** 438251875Speter * Allocate a block of memory from a pool and set all of the memory to 0 439251875Speter * @param p The pool to allocate from 440251875Speter * @param size The amount of memory to allocate 441251875Speter * @return The allocated memory 442251875Speter */ 443251875Speter#if defined(DOXYGEN) 444251875SpeterAPR_DECLARE(void *) apr_pcalloc(apr_pool_t *p, apr_size_t size); 445251875Speter#elif !APR_POOL_DEBUG 446251875Speter#define apr_pcalloc(p, size) memset(apr_palloc(p, size), 0, size) 447251875Speter#endif 448251875Speter 449251875Speter/** 450251875Speter * Debug version of apr_pcalloc 451251875Speter * @param p See: apr_pcalloc 452251875Speter * @param size See: apr_pcalloc 453251875Speter * @param file_line Where the function is called from. 454251875Speter * This is usually APR_POOL__FILE_LINE__. 455251875Speter * @return See: apr_pcalloc 456251875Speter */ 457251875SpeterAPR_DECLARE(void *) apr_pcalloc_debug(apr_pool_t *p, apr_size_t size, 458251875Speter const char *file_line); 459251875Speter 460251875Speter#if APR_POOL_DEBUG 461251875Speter#define apr_pcalloc(p, size) \ 462251875Speter apr_pcalloc_debug(p, size, APR_POOL__FILE_LINE__) 463251875Speter#endif 464251875Speter 465251875Speter 466251875Speter/* 467251875Speter * Pool Properties 468251875Speter */ 469251875Speter 470251875Speter/** 471251875Speter * Set the function to be called when an allocation failure occurs. 472251875Speter * @remark If the program wants APR to exit on a memory allocation error, 473251875Speter * then this function can be called to set the callback to use (for 474251875Speter * performing cleanup and then exiting). If this function is not called, 475251875Speter * then APR will return an error and expect the calling program to 476251875Speter * deal with the error accordingly. 477251875Speter */ 478251875SpeterAPR_DECLARE(void) apr_pool_abort_set(apr_abortfunc_t abortfunc, 479251875Speter apr_pool_t *pool); 480251875Speter 481251875Speter/** 482251875Speter * Get the abort function associated with the specified pool. 483251875Speter * @param pool The pool for retrieving the abort function. 484251875Speter * @return The abort function for the given pool. 485251875Speter */ 486251875SpeterAPR_DECLARE(apr_abortfunc_t) apr_pool_abort_get(apr_pool_t *pool); 487251875Speter 488251875Speter/** 489251875Speter * Get the parent pool of the specified pool. 490251875Speter * @param pool The pool for retrieving the parent pool. 491251875Speter * @return The parent of the given pool. 492251875Speter */ 493251875SpeterAPR_DECLARE(apr_pool_t *) apr_pool_parent_get(apr_pool_t *pool); 494251875Speter 495251875Speter/** 496251875Speter * Determine if pool a is an ancestor of pool b. 497251875Speter * @param a The pool to search 498251875Speter * @param b The pool to search for 499251875Speter * @return True if a is an ancestor of b, NULL is considered an ancestor 500251875Speter * of all pools. 501251875Speter * @remark if compiled with APR_POOL_DEBUG, this function will also 502251875Speter * return true if A is a pool which has been guaranteed by the caller 503251875Speter * (using apr_pool_join) to have a lifetime at least as long as some 504251875Speter * ancestor of pool B. 505251875Speter */ 506251875SpeterAPR_DECLARE(int) apr_pool_is_ancestor(apr_pool_t *a, apr_pool_t *b); 507251875Speter 508251875Speter/** 509251875Speter * Tag a pool (give it a name) 510251875Speter * @param pool The pool to tag 511251875Speter * @param tag The tag 512251875Speter */ 513251875SpeterAPR_DECLARE(void) apr_pool_tag(apr_pool_t *pool, const char *tag); 514251875Speter 515251875Speter 516251875Speter/* 517251875Speter * User data management 518251875Speter */ 519251875Speter 520251875Speter/** 521251875Speter * Set the data associated with the current pool 522251875Speter * @param data The user data associated with the pool. 523251875Speter * @param key The key to use for association 524251875Speter * @param cleanup The cleanup program to use to cleanup the data (NULL if none) 525251875Speter * @param pool The current pool 526251875Speter * @warning The data to be attached to the pool should have a life span 527251875Speter * at least as long as the pool it is being attached to. 528251875Speter * 529251875Speter * Users of APR must take EXTREME care when choosing a key to 530251875Speter * use for their data. It is possible to accidentally overwrite 531251875Speter * data by choosing a key that another part of the program is using. 532251875Speter * Therefore it is advised that steps are taken to ensure that unique 533251875Speter * keys are used for all of the userdata objects in a particular pool 534251875Speter * (the same key in two different pools or a pool and one of its 535251875Speter * subpools is okay) at all times. Careful namespace prefixing of 536251875Speter * key names is a typical way to help ensure this uniqueness. 537251875Speter * 538251875Speter */ 539251875SpeterAPR_DECLARE(apr_status_t) apr_pool_userdata_set( 540251875Speter const void *data, 541251875Speter const char *key, 542251875Speter apr_status_t (*cleanup)(void *), 543251875Speter apr_pool_t *pool); 544251875Speter 545251875Speter/** 546251875Speter * Set the data associated with the current pool 547251875Speter * @param data The user data associated with the pool. 548251875Speter * @param key The key to use for association 549251875Speter * @param cleanup The cleanup program to use to cleanup the data (NULL if none) 550251875Speter * @param pool The current pool 551251875Speter * @note same as apr_pool_userdata_set(), except that this version doesn't 552251875Speter * make a copy of the key (this function is useful, for example, when 553251875Speter * the key is a string literal) 554251875Speter * @warning This should NOT be used if the key could change addresses by 555251875Speter * any means between the apr_pool_userdata_setn() call and a 556251875Speter * subsequent apr_pool_userdata_get() on that key, such as if a 557251875Speter * static string is used as a userdata key in a DSO and the DSO could 558251875Speter * be unloaded and reloaded between the _setn() and the _get(). You 559251875Speter * MUST use apr_pool_userdata_set() in such cases. 560251875Speter * @warning More generally, the key and the data to be attached to the 561251875Speter * pool should have a life span at least as long as the pool itself. 562251875Speter * 563251875Speter */ 564251875SpeterAPR_DECLARE(apr_status_t) apr_pool_userdata_setn( 565251875Speter const void *data, 566251875Speter const char *key, 567251875Speter apr_status_t (*cleanup)(void *), 568251875Speter apr_pool_t *pool); 569251875Speter 570251875Speter/** 571251875Speter * Return the data associated with the current pool. 572251875Speter * @param data The user data associated with the pool. 573251875Speter * @param key The key for the data to retrieve 574251875Speter * @param pool The current pool. 575251875Speter */ 576251875SpeterAPR_DECLARE(apr_status_t) apr_pool_userdata_get(void **data, const char *key, 577251875Speter apr_pool_t *pool); 578251875Speter 579251875Speter 580251875Speter/** 581251875Speter * @defgroup PoolCleanup Pool Cleanup Functions 582251875Speter * 583251875Speter * Cleanups are performed in the reverse order they were registered. That is: 584251875Speter * Last In, First Out. A cleanup function can safely allocate memory from 585251875Speter * the pool that is being cleaned up. It can also safely register additional 586251875Speter * cleanups which will be run LIFO, directly after the current cleanup 587251875Speter * terminates. Cleanups have to take caution in calling functions that 588251875Speter * create subpools. Subpools, created during cleanup will NOT automatically 589251875Speter * be cleaned up. In other words, cleanups are to clean up after themselves. 590251875Speter * 591251875Speter * @{ 592251875Speter */ 593251875Speter 594251875Speter/** 595251875Speter * Register a function to be called when a pool is cleared or destroyed 596251875Speter * @param p The pool register the cleanup with 597251875Speter * @param data The data to pass to the cleanup function. 598251875Speter * @param plain_cleanup The function to call when the pool is cleared 599251875Speter * or destroyed 600251875Speter * @param child_cleanup The function to call when a child process is about 601251875Speter * to exec - this function is called in the child, obviously! 602251875Speter */ 603251875SpeterAPR_DECLARE(void) apr_pool_cleanup_register( 604251875Speter apr_pool_t *p, 605251875Speter const void *data, 606251875Speter apr_status_t (*plain_cleanup)(void *), 607251875Speter apr_status_t (*child_cleanup)(void *)); 608251875Speter 609251875Speter/** 610251875Speter * Register a function to be called when a pool is cleared or destroyed. 611251875Speter * 612251875Speter * Unlike apr_pool_cleanup_register which register a cleanup 613251875Speter * that is called AFTER all subpools are destroyed this function register 614251875Speter * a function that will be called before any of the subpool is destoryed. 615251875Speter * 616251875Speter * @param p The pool register the cleanup with 617251875Speter * @param data The data to pass to the cleanup function. 618251875Speter * @param plain_cleanup The function to call when the pool is cleared 619251875Speter * or destroyed 620251875Speter */ 621251875SpeterAPR_DECLARE(void) apr_pool_pre_cleanup_register( 622251875Speter apr_pool_t *p, 623251875Speter const void *data, 624251875Speter apr_status_t (*plain_cleanup)(void *)); 625251875Speter 626251875Speter/** 627251875Speter * Remove a previously registered cleanup function. 628251875Speter * 629251875Speter * The cleanup most recently registered with @a p having the same values of 630251875Speter * @a data and @a cleanup will be removed. 631251875Speter * 632251875Speter * @param p The pool to remove the cleanup from 633251875Speter * @param data The data of the registered cleanup 634251875Speter * @param cleanup The function to remove from cleanup 635251875Speter * @remarks For some strange reason only the plain_cleanup is handled by this 636251875Speter * function 637251875Speter */ 638251875SpeterAPR_DECLARE(void) apr_pool_cleanup_kill(apr_pool_t *p, const void *data, 639251875Speter apr_status_t (*cleanup)(void *)); 640251875Speter 641251875Speter/** 642251875Speter * Replace the child cleanup function of a previously registered cleanup. 643251875Speter * 644251875Speter * The cleanup most recently registered with @a p having the same values of 645251875Speter * @a data and @a plain_cleanup will have the registered child cleanup 646251875Speter * function replaced with @a child_cleanup. 647251875Speter * 648251875Speter * @param p The pool of the registered cleanup 649251875Speter * @param data The data of the registered cleanup 650251875Speter * @param plain_cleanup The plain cleanup function of the registered cleanup 651251875Speter * @param child_cleanup The function to register as the child cleanup 652251875Speter */ 653251875SpeterAPR_DECLARE(void) apr_pool_child_cleanup_set( 654251875Speter apr_pool_t *p, 655251875Speter const void *data, 656251875Speter apr_status_t (*plain_cleanup)(void *), 657251875Speter apr_status_t (*child_cleanup)(void *)); 658251875Speter 659251875Speter/** 660251875Speter * Run the specified cleanup function immediately and unregister it. 661251875Speter * 662251875Speter * The cleanup most recently registered with @a p having the same values of 663251875Speter * @a data and @a cleanup will be removed and @a cleanup will be called 664251875Speter * with @a data as the argument. 665251875Speter * 666251875Speter * @param p The pool to remove the cleanup from 667251875Speter * @param data The data to remove from cleanup 668251875Speter * @param cleanup The function to remove from cleanup 669251875Speter */ 670251875SpeterAPR_DECLARE(apr_status_t) apr_pool_cleanup_run( 671251875Speter apr_pool_t *p, 672251875Speter void *data, 673251875Speter apr_status_t (*cleanup)(void *)); 674251875Speter 675251875Speter/** 676251875Speter * An empty cleanup function. 677251875Speter * 678251875Speter * Passed to apr_pool_cleanup_register() when no cleanup is required. 679251875Speter * 680251875Speter * @param data The data to cleanup, will not be used by this function. 681251875Speter */ 682251875SpeterAPR_DECLARE_NONSTD(apr_status_t) apr_pool_cleanup_null(void *data); 683251875Speter 684251875Speter/** 685251875Speter * Run all registered child cleanups, in preparation for an exec() 686251875Speter * call in a forked child -- close files, etc., but *don't* flush I/O 687251875Speter * buffers, *don't* wait for subprocesses, and *don't* free any 688251875Speter * memory. 689251875Speter */ 690251875SpeterAPR_DECLARE(void) apr_pool_cleanup_for_exec(void); 691251875Speter 692251875Speter/** @} */ 693251875Speter 694251875Speter/** 695251875Speter * @defgroup PoolDebug Pool Debugging functions. 696251875Speter * 697251875Speter * pools have nested lifetimes -- sub_pools are destroyed when the 698251875Speter * parent pool is cleared. We allow certain liberties with operations 699251875Speter * on things such as tables (and on other structures in a more general 700251875Speter * sense) where we allow the caller to insert values into a table which 701251875Speter * were not allocated from the table's pool. The table's data will 702251875Speter * remain valid as long as all the pools from which its values are 703251875Speter * allocated remain valid. 704251875Speter * 705251875Speter * For example, if B is a sub pool of A, and you build a table T in 706251875Speter * pool B, then it's safe to insert data allocated in A or B into T 707251875Speter * (because B lives at most as long as A does, and T is destroyed when 708251875Speter * B is cleared/destroyed). On the other hand, if S is a table in 709251875Speter * pool A, it is safe to insert data allocated in A into S, but it 710251875Speter * is *not safe* to insert data allocated from B into S... because 711251875Speter * B can be cleared/destroyed before A is (which would leave dangling 712251875Speter * pointers in T's data structures). 713251875Speter * 714251875Speter * In general we say that it is safe to insert data into a table T 715251875Speter * if the data is allocated in any ancestor of T's pool. This is the 716251875Speter * basis on which the APR_POOL_DEBUG code works -- it tests these ancestor 717251875Speter * relationships for all data inserted into tables. APR_POOL_DEBUG also 718251875Speter * provides tools (apr_pool_find, and apr_pool_is_ancestor) for other 719251875Speter * folks to implement similar restrictions for their own data 720251875Speter * structures. 721251875Speter * 722251875Speter * However, sometimes this ancestor requirement is inconvenient -- 723251875Speter * sometimes it's necessary to create a sub pool where the sub pool is 724251875Speter * guaranteed to have the same lifetime as the parent pool. This is a 725251875Speter * guarantee implemented by the *caller*, not by the pool code. That 726251875Speter * is, the caller guarantees they won't destroy the sub pool 727251875Speter * individually prior to destroying the parent pool. 728251875Speter * 729251875Speter * In this case the caller must call apr_pool_join() to indicate this 730251875Speter * guarantee to the APR_POOL_DEBUG code. 731251875Speter * 732251875Speter * These functions are only implemented when #APR_POOL_DEBUG is set. 733251875Speter * 734251875Speter * @{ 735251875Speter */ 736251875Speter#if APR_POOL_DEBUG || defined(DOXYGEN) 737251875Speter/** 738251875Speter * Guarantee that a subpool has the same lifetime as the parent. 739251875Speter * @param p The parent pool 740251875Speter * @param sub The subpool 741251875Speter */ 742251875SpeterAPR_DECLARE(void) apr_pool_join(apr_pool_t *p, apr_pool_t *sub); 743251875Speter 744251875Speter/** 745251875Speter * Find a pool from something allocated in it. 746251875Speter * @param mem The thing allocated in the pool 747251875Speter * @return The pool it is allocated in 748251875Speter */ 749251875SpeterAPR_DECLARE(apr_pool_t *) apr_pool_find(const void *mem); 750251875Speter 751251875Speter/** 752251875Speter * Report the number of bytes currently in the pool 753251875Speter * @param p The pool to inspect 754251875Speter * @param recurse Recurse/include the subpools' sizes 755251875Speter * @return The number of bytes 756251875Speter */ 757251875SpeterAPR_DECLARE(apr_size_t) apr_pool_num_bytes(apr_pool_t *p, int recurse); 758251875Speter 759251875Speter/** 760251875Speter * Lock a pool 761251875Speter * @param pool The pool to lock 762251875Speter * @param flag The flag 763251875Speter */ 764251875SpeterAPR_DECLARE(void) apr_pool_lock(apr_pool_t *pool, int flag); 765251875Speter 766251875Speter/* @} */ 767251875Speter 768251875Speter#else /* APR_POOL_DEBUG or DOXYGEN */ 769251875Speter 770251875Speter#ifdef apr_pool_join 771251875Speter#undef apr_pool_join 772251875Speter#endif 773251875Speter#define apr_pool_join(a,b) 774251875Speter 775251875Speter#ifdef apr_pool_lock 776251875Speter#undef apr_pool_lock 777251875Speter#endif 778251875Speter#define apr_pool_lock(pool, lock) 779251875Speter 780251875Speter#endif /* APR_POOL_DEBUG or DOXYGEN */ 781251875Speter 782251875Speter/** @} */ 783251875Speter 784251875Speter#ifdef __cplusplus 785251875Speter} 786251875Speter#endif 787251875Speter 788251875Speter#endif /* !APR_POOLS_H */ 789