Annotation of win32/apache22/srclib/apr/include/apr_pools.h, revision 1.1
1.1 ! moko 1: /* Licensed to the Apache Software Foundation (ASF) under one or more
! 2: * contributor license agreements. See the NOTICE file distributed with
! 3: * this work for additional information regarding copyright ownership.
! 4: * The ASF licenses this file to You under the Apache License, Version 2.0
! 5: * (the "License"); you may not use this file except in compliance with
! 6: * the License. You may obtain a copy of the License at
! 7: *
! 8: * http://www.apache.org/licenses/LICENSE-2.0
! 9: *
! 10: * Unless required by applicable law or agreed to in writing, software
! 11: * distributed under the License is distributed on an "AS IS" BASIS,
! 12: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
! 13: * See the License for the specific language governing permissions and
! 14: * limitations under the License.
! 15: */
! 16:
! 17: #ifndef APR_POOLS_H
! 18: #define APR_POOLS_H
! 19:
! 20: /**
! 21: * @file apr_pools.h
! 22: * @brief APR memory allocation
! 23: *
! 24: * Resource allocation routines...
! 25: *
! 26: * designed so that we don't have to keep track of EVERYTHING so that
! 27: * it can be explicitly freed later (a fundamentally unsound strategy ---
! 28: * particularly in the presence of die()).
! 29: *
! 30: * Instead, we maintain pools, and allocate items (both memory and I/O
! 31: * handlers) from the pools --- currently there are two, one for
! 32: * per-transaction info, and one for config info. When a transaction is
! 33: * over, we can delete everything in the per-transaction apr_pool_t without
! 34: * fear, and without thinking too hard about it either.
! 35: *
! 36: * Note that most operations on pools are not thread-safe: a single pool
! 37: * should only be accessed by a single thread at any given time. The one
! 38: * exception to this rule is creating a subpool of a given pool: one or more
! 39: * threads can safely create subpools at the same time that another thread
! 40: * accesses the parent pool.
! 41: */
! 42:
! 43: #include "apr.h"
! 44: #include "apr_errno.h"
! 45: #include "apr_general.h" /* for APR_STRINGIFY */
! 46: #define APR_WANT_MEMFUNC /**< for no good reason? */
! 47: #include "apr_want.h"
! 48:
! 49: #ifdef __cplusplus
! 50: extern "C" {
! 51: #endif
! 52:
! 53: /**
! 54: * @defgroup apr_pools Memory Pool Functions
! 55: * @ingroup APR
! 56: * @{
! 57: */
! 58:
! 59: /** The fundamental pool type */
! 60: typedef struct apr_pool_t apr_pool_t;
! 61:
! 62:
! 63: /**
! 64: * Declaration helper macro to construct apr_foo_pool_get()s.
! 65: *
! 66: * This standardized macro is used by opaque (APR) data types to return
! 67: * the apr_pool_t that is associated with the data type.
! 68: *
! 69: * APR_POOL_DECLARE_ACCESSOR() is used in a header file to declare the
! 70: * accessor function. A typical usage and result would be:
! 71: * <pre>
! 72: * APR_POOL_DECLARE_ACCESSOR(file);
! 73: * becomes:
! 74: * APR_DECLARE(apr_pool_t *) apr_file_pool_get(apr_file_t *ob);
! 75: * </pre>
! 76: * @remark Doxygen unwraps this macro (via doxygen.conf) to provide
! 77: * actual help for each specific occurance of apr_foo_pool_get.
! 78: * @remark the linkage is specified for APR. It would be possible to expand
! 79: * the macros to support other linkages.
! 80: */
! 81: #define APR_POOL_DECLARE_ACCESSOR(type) \
! 82: APR_DECLARE(apr_pool_t *) apr_##type##_pool_get \
! 83: (const apr_##type##_t *the##type)
! 84:
! 85: /**
! 86: * Implementation helper macro to provide apr_foo_pool_get()s.
! 87: *
! 88: * In the implementation, the APR_POOL_IMPLEMENT_ACCESSOR() is used to
! 89: * actually define the function. It assumes the field is named "pool".
! 90: */
! 91: #define APR_POOL_IMPLEMENT_ACCESSOR(type) \
! 92: APR_DECLARE(apr_pool_t *) apr_##type##_pool_get \
! 93: (const apr_##type##_t *the##type) \
! 94: { return the##type->pool; }
! 95:
! 96:
! 97: /**
! 98: * Pool debug levels
! 99: *
! 100: * <pre>
! 101: * | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
! 102: * ---------------------------------
! 103: * | | | | | | | | x | General debug code enabled (useful in
! 104: * combination with --with-efence).
! 105: *
! 106: * | | | | | | | x | | Verbose output on stderr (report
! 107: * CREATE, CLEAR, DESTROY).
! 108: *
! 109: * | | | | x | | | | | Verbose output on stderr (report
! 110: * PALLOC, PCALLOC).
! 111: *
! 112: * | | | | | | x | | | Lifetime checking. On each use of a
! 113: * pool, check its lifetime. If the pool
! 114: * is out of scope, abort().
! 115: * In combination with the verbose flag
! 116: * above, it will output LIFE in such an
! 117: * event prior to aborting.
! 118: *
! 119: * | | | | | x | | | | Pool owner checking. On each use of a
! 120: * pool, check if the current thread is the
! 121: * pools owner. If not, abort(). In
! 122: * combination with the verbose flag above,
! 123: * it will output OWNER in such an event
! 124: * prior to aborting. Use the debug
! 125: * function apr_pool_owner_set() to switch
! 126: * a pools ownership.
! 127: *
! 128: * When no debug level was specified, assume general debug mode.
! 129: * If level 0 was specified, debugging is switched off
! 130: * </pre>
! 131: */
! 132: #if defined(APR_POOL_DEBUG)
! 133: /* If APR_POOL_DEBUG is blank, we get 1; if it is a number, we get -1. */
! 134: #if (APR_POOL_DEBUG - APR_POOL_DEBUG -1 == 1)
! 135: #undef APR_POOL_DEBUG
! 136: #define APR_POOL_DEBUG 1
! 137: #endif
! 138: #else
! 139: #define APR_POOL_DEBUG 0
! 140: #endif
! 141:
! 142: /** the place in the code where the particular function was called */
! 143: #define APR_POOL__FILE_LINE__ __FILE__ ":" APR_STRINGIFY(__LINE__)
! 144:
! 145:
! 146:
! 147: /** A function that is called when allocation fails. */
! 148: typedef int (*apr_abortfunc_t)(int retcode);
! 149:
! 150: /*
! 151: * APR memory structure manipulators (pools, tables, and arrays).
! 152: */
! 153:
! 154: /*
! 155: * Initialization
! 156: */
! 157:
! 158: /**
! 159: * Setup all of the internal structures required to use pools
! 160: * @remark Programs do NOT need to call this directly. APR will call this
! 161: * automatically from apr_initialize.
! 162: * @internal
! 163: */
! 164: APR_DECLARE(apr_status_t) apr_pool_initialize(void);
! 165:
! 166: /**
! 167: * Tear down all of the internal structures required to use pools
! 168: * @remark Programs do NOT need to call this directly. APR will call this
! 169: * automatically from apr_terminate.
! 170: * @internal
! 171: */
! 172: APR_DECLARE(void) apr_pool_terminate(void);
! 173:
! 174:
! 175: /*
! 176: * Pool creation/destruction
! 177: */
! 178:
! 179: #include "apr_allocator.h"
! 180:
! 181: /**
! 182: * Create a new pool.
! 183: * @param newpool The pool we have just created.
! 184: * @param parent The parent pool. If this is NULL, the new pool is a root
! 185: * pool. If it is non-NULL, the new pool will inherit all
! 186: * of its parent pool's attributes, except the apr_pool_t will
! 187: * be a sub-pool.
! 188: * @param abort_fn A function to use if the pool cannot allocate more memory.
! 189: * @param allocator The allocator to use with the new pool. If NULL the
! 190: * allocator of the parent pool will be used.
! 191: * @remark This function is thread-safe, in the sense that multiple threads
! 192: * can safely create subpools of the same parent pool concurrently.
! 193: * Similarly, a subpool can be created by one thread at the same
! 194: * time that another thread accesses the parent pool.
! 195: */
! 196: APR_DECLARE(apr_status_t) apr_pool_create_ex(apr_pool_t **newpool,
! 197: apr_pool_t *parent,
! 198: apr_abortfunc_t abort_fn,
! 199: apr_allocator_t *allocator)
! 200: __attribute__((nonnull(1)));
! 201:
! 202: /**
! 203: * Create a new pool.
! 204: * @deprecated @see apr_pool_create_unmanaged_ex.
! 205: */
! 206: APR_DECLARE(apr_status_t) apr_pool_create_core_ex(apr_pool_t **newpool,
! 207: apr_abortfunc_t abort_fn,
! 208: apr_allocator_t *allocator);
! 209:
! 210: /**
! 211: * Create a new unmanaged pool.
! 212: * @param newpool The pool we have just created.
! 213: * @param abort_fn A function to use if the pool cannot allocate more memory.
! 214: * @param allocator The allocator to use with the new pool. If NULL a
! 215: * new allocator will be crated with newpool as owner.
! 216: * @remark An unmanaged pool is a special pool without a parent; it will
! 217: * NOT be destroyed upon apr_terminate. It must be explicitly
! 218: * destroyed by calling apr_pool_destroy, to prevent memory leaks.
! 219: * Use of this function is discouraged, think twice about whether
! 220: * you really really need it.
! 221: */
! 222: APR_DECLARE(apr_status_t) apr_pool_create_unmanaged_ex(apr_pool_t **newpool,
! 223: apr_abortfunc_t abort_fn,
! 224: apr_allocator_t *allocator)
! 225: __attribute__((nonnull(1)));
! 226:
! 227: /**
! 228: * Debug version of apr_pool_create_ex.
! 229: * @param newpool @see apr_pool_create.
! 230: * @param parent @see apr_pool_create.
! 231: * @param abort_fn @see apr_pool_create.
! 232: * @param allocator @see apr_pool_create.
! 233: * @param file_line Where the function is called from.
! 234: * This is usually APR_POOL__FILE_LINE__.
! 235: * @remark Only available when APR_POOL_DEBUG is defined.
! 236: * Call this directly if you have you apr_pool_create_ex
! 237: * calls in a wrapper function and wish to override
! 238: * the file_line argument to reflect the caller of
! 239: * your wrapper function. If you do not have
! 240: * apr_pool_create_ex in a wrapper, trust the macro
! 241: * and don't call apr_pool_create_ex_debug directly.
! 242: */
! 243: APR_DECLARE(apr_status_t) apr_pool_create_ex_debug(apr_pool_t **newpool,
! 244: apr_pool_t *parent,
! 245: apr_abortfunc_t abort_fn,
! 246: apr_allocator_t *allocator,
! 247: const char *file_line)
! 248: __attribute__((nonnull(1)));
! 249:
! 250: #if APR_POOL_DEBUG
! 251: #define apr_pool_create_ex(newpool, parent, abort_fn, allocator) \
! 252: apr_pool_create_ex_debug(newpool, parent, abort_fn, allocator, \
! 253: APR_POOL__FILE_LINE__)
! 254: #endif
! 255:
! 256: /**
! 257: * Debug version of apr_pool_create_core_ex.
! 258: * @deprecated @see apr_pool_create_unmanaged_ex_debug.
! 259: */
! 260: APR_DECLARE(apr_status_t) apr_pool_create_core_ex_debug(apr_pool_t **newpool,
! 261: apr_abortfunc_t abort_fn,
! 262: apr_allocator_t *allocator,
! 263: const char *file_line);
! 264:
! 265: /**
! 266: * Debug version of apr_pool_create_unmanaged_ex.
! 267: * @param newpool @see apr_pool_create_unmanaged.
! 268: * @param abort_fn @see apr_pool_create_unmanaged.
! 269: * @param allocator @see apr_pool_create_unmanaged.
! 270: * @param file_line Where the function is called from.
! 271: * This is usually APR_POOL__FILE_LINE__.
! 272: * @remark Only available when APR_POOL_DEBUG is defined.
! 273: * Call this directly if you have you apr_pool_create_unmanaged_ex
! 274: * calls in a wrapper function and wish to override
! 275: * the file_line argument to reflect the caller of
! 276: * your wrapper function. If you do not have
! 277: * apr_pool_create_core_ex in a wrapper, trust the macro
! 278: * and don't call apr_pool_create_core_ex_debug directly.
! 279: */
! 280: APR_DECLARE(apr_status_t) apr_pool_create_unmanaged_ex_debug(apr_pool_t **newpool,
! 281: apr_abortfunc_t abort_fn,
! 282: apr_allocator_t *allocator,
! 283: const char *file_line)
! 284: __attribute__((nonnull(1)));
! 285:
! 286: #if APR_POOL_DEBUG
! 287: #define apr_pool_create_core_ex(newpool, abort_fn, allocator) \
! 288: apr_pool_create_unmanaged_ex_debug(newpool, abort_fn, allocator, \
! 289: APR_POOL__FILE_LINE__)
! 290:
! 291: #define apr_pool_create_unmanaged_ex(newpool, abort_fn, allocator) \
! 292: apr_pool_create_unmanaged_ex_debug(newpool, abort_fn, allocator, \
! 293: APR_POOL__FILE_LINE__)
! 294:
! 295: #endif
! 296:
! 297: /**
! 298: * Create a new pool.
! 299: * @param newpool The pool we have just created.
! 300: * @param parent The parent pool. If this is NULL, the new pool is a root
! 301: * pool. If it is non-NULL, the new pool will inherit all
! 302: * of its parent pool's attributes, except the apr_pool_t will
! 303: * be a sub-pool.
! 304: * @remark This function is thread-safe, in the sense that multiple threads
! 305: * can safely create subpools of the same parent pool concurrently.
! 306: * Similarly, a subpool can be created by one thread at the same
! 307: * time that another thread accesses the parent pool.
! 308: */
! 309: #if defined(DOXYGEN)
! 310: APR_DECLARE(apr_status_t) apr_pool_create(apr_pool_t **newpool,
! 311: apr_pool_t *parent);
! 312: #else
! 313: #if APR_POOL_DEBUG
! 314: #define apr_pool_create(newpool, parent) \
! 315: apr_pool_create_ex_debug(newpool, parent, NULL, NULL, \
! 316: APR_POOL__FILE_LINE__)
! 317: #else
! 318: #define apr_pool_create(newpool, parent) \
! 319: apr_pool_create_ex(newpool, parent, NULL, NULL)
! 320: #endif
! 321: #endif
! 322:
! 323: /**
! 324: * Create a new pool.
! 325: * @param newpool The pool we have just created.
! 326: */
! 327: #if defined(DOXYGEN)
! 328: APR_DECLARE(apr_status_t) apr_pool_create_core(apr_pool_t **newpool);
! 329: APR_DECLARE(apr_status_t) apr_pool_create_unmanaged(apr_pool_t **newpool);
! 330: #else
! 331: #if APR_POOL_DEBUG
! 332: #define apr_pool_create_core(newpool) \
! 333: apr_pool_create_unmanaged_ex_debug(newpool, NULL, NULL, \
! 334: APR_POOL__FILE_LINE__)
! 335: #define apr_pool_create_unmanaged(newpool) \
! 336: apr_pool_create_unmanaged_ex_debug(newpool, NULL, NULL, \
! 337: APR_POOL__FILE_LINE__)
! 338: #else
! 339: #define apr_pool_create_core(newpool) \
! 340: apr_pool_create_unmanaged_ex(newpool, NULL, NULL)
! 341: #define apr_pool_create_unmanaged(newpool) \
! 342: apr_pool_create_unmanaged_ex(newpool, NULL, NULL)
! 343: #endif
! 344: #endif
! 345:
! 346: /**
! 347: * Find the pool's allocator
! 348: * @param pool The pool to get the allocator from.
! 349: */
! 350: APR_DECLARE(apr_allocator_t *) apr_pool_allocator_get(apr_pool_t *pool)
! 351: __attribute__((nonnull(1)));
! 352:
! 353: /**
! 354: * Clear all memory in the pool and run all the cleanups. This also destroys all
! 355: * subpools.
! 356: * @param p The pool to clear
! 357: * @remark This does not actually free the memory, it just allows the pool
! 358: * to re-use this memory for the next allocation.
! 359: * @see apr_pool_destroy()
! 360: */
! 361: APR_DECLARE(void) apr_pool_clear(apr_pool_t *p) __attribute__((nonnull(1)));
! 362:
! 363: /**
! 364: * Debug version of apr_pool_clear.
! 365: * @param p See: apr_pool_clear.
! 366: * @param file_line Where the function is called from.
! 367: * This is usually APR_POOL__FILE_LINE__.
! 368: * @remark Only available when APR_POOL_DEBUG is defined.
! 369: * Call this directly if you have you apr_pool_clear
! 370: * calls in a wrapper function and wish to override
! 371: * the file_line argument to reflect the caller of
! 372: * your wrapper function. If you do not have
! 373: * apr_pool_clear in a wrapper, trust the macro
! 374: * and don't call apr_pool_destroy_clear directly.
! 375: */
! 376: APR_DECLARE(void) apr_pool_clear_debug(apr_pool_t *p,
! 377: const char *file_line)
! 378: __attribute__((nonnull(1)));
! 379:
! 380: #if APR_POOL_DEBUG
! 381: #define apr_pool_clear(p) \
! 382: apr_pool_clear_debug(p, APR_POOL__FILE_LINE__)
! 383: #endif
! 384:
! 385: /**
! 386: * Destroy the pool. This takes similar action as apr_pool_clear() and then
! 387: * frees all the memory.
! 388: * @param p The pool to destroy
! 389: * @remark This will actually free the memory
! 390: */
! 391: APR_DECLARE(void) apr_pool_destroy(apr_pool_t *p) __attribute__((nonnull(1)));
! 392:
! 393: /**
! 394: * Debug version of apr_pool_destroy.
! 395: * @param p See: apr_pool_destroy.
! 396: * @param file_line Where the function is called from.
! 397: * This is usually APR_POOL__FILE_LINE__.
! 398: * @remark Only available when APR_POOL_DEBUG is defined.
! 399: * Call this directly if you have you apr_pool_destroy
! 400: * calls in a wrapper function and wish to override
! 401: * the file_line argument to reflect the caller of
! 402: * your wrapper function. If you do not have
! 403: * apr_pool_destroy in a wrapper, trust the macro
! 404: * and don't call apr_pool_destroy_debug directly.
! 405: */
! 406: APR_DECLARE(void) apr_pool_destroy_debug(apr_pool_t *p,
! 407: const char *file_line)
! 408: __attribute__((nonnull(1)));
! 409:
! 410: #if APR_POOL_DEBUG
! 411: #define apr_pool_destroy(p) \
! 412: apr_pool_destroy_debug(p, APR_POOL__FILE_LINE__)
! 413: #endif
! 414:
! 415:
! 416: /*
! 417: * Memory allocation
! 418: */
! 419:
! 420: /**
! 421: * Allocate a block of memory from a pool
! 422: * @param p The pool to allocate from
! 423: * @param size The amount of memory to allocate
! 424: * @return The allocated memory
! 425: */
! 426: APR_DECLARE(void *) apr_palloc(apr_pool_t *p, apr_size_t size)
! 427: #if defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4))
! 428: __attribute__((alloc_size(2)))
! 429: #endif
! 430: __attribute__((nonnull(1)));
! 431:
! 432: /**
! 433: * Debug version of apr_palloc
! 434: * @param p See: apr_palloc
! 435: * @param size See: apr_palloc
! 436: * @param file_line Where the function is called from.
! 437: * This is usually APR_POOL__FILE_LINE__.
! 438: * @return See: apr_palloc
! 439: */
! 440: APR_DECLARE(void *) apr_palloc_debug(apr_pool_t *p, apr_size_t size,
! 441: const char *file_line)
! 442: #if defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4))
! 443: __attribute__((alloc_size(2)))
! 444: #endif
! 445: __attribute__((nonnull(1)));
! 446:
! 447: #if APR_POOL_DEBUG
! 448: #define apr_palloc(p, size) \
! 449: apr_palloc_debug(p, size, APR_POOL__FILE_LINE__)
! 450: #endif
! 451:
! 452: /**
! 453: * Allocate a block of memory from a pool and set all of the memory to 0
! 454: * @param p The pool to allocate from
! 455: * @param size The amount of memory to allocate
! 456: * @return The allocated memory
! 457: */
! 458: #if defined(DOXYGEN)
! 459: APR_DECLARE(void *) apr_pcalloc(apr_pool_t *p, apr_size_t size);
! 460: #elif !APR_POOL_DEBUG
! 461: #define apr_pcalloc(p, size) memset(apr_palloc(p, size), 0, size)
! 462: #endif
! 463:
! 464: /**
! 465: * Debug version of apr_pcalloc
! 466: * @param p See: apr_pcalloc
! 467: * @param size See: apr_pcalloc
! 468: * @param file_line Where the function is called from.
! 469: * This is usually APR_POOL__FILE_LINE__.
! 470: * @return See: apr_pcalloc
! 471: */
! 472: APR_DECLARE(void *) apr_pcalloc_debug(apr_pool_t *p, apr_size_t size,
! 473: const char *file_line)
! 474: __attribute__((nonnull(1)));
! 475:
! 476: #if APR_POOL_DEBUG
! 477: #define apr_pcalloc(p, size) \
! 478: apr_pcalloc_debug(p, size, APR_POOL__FILE_LINE__)
! 479: #endif
! 480:
! 481:
! 482: /*
! 483: * Pool Properties
! 484: */
! 485:
! 486: /**
! 487: * Set the function to be called when an allocation failure occurs.
! 488: * @remark If the program wants APR to exit on a memory allocation error,
! 489: * then this function can be called to set the callback to use (for
! 490: * performing cleanup and then exiting). If this function is not called,
! 491: * then APR will return an error and expect the calling program to
! 492: * deal with the error accordingly.
! 493: */
! 494: APR_DECLARE(void) apr_pool_abort_set(apr_abortfunc_t abortfunc,
! 495: apr_pool_t *pool)
! 496: __attribute__((nonnull(2)));
! 497:
! 498: /**
! 499: * Get the abort function associated with the specified pool.
! 500: * @param pool The pool for retrieving the abort function.
! 501: * @return The abort function for the given pool.
! 502: */
! 503: APR_DECLARE(apr_abortfunc_t) apr_pool_abort_get(apr_pool_t *pool)
! 504: __attribute__((nonnull(1)));
! 505:
! 506: /**
! 507: * Get the parent pool of the specified pool.
! 508: * @param pool The pool for retrieving the parent pool.
! 509: * @return The parent of the given pool.
! 510: */
! 511: APR_DECLARE(apr_pool_t *) apr_pool_parent_get(apr_pool_t *pool)
! 512: __attribute__((nonnull(1)));
! 513:
! 514: /**
! 515: * Determine if pool a is an ancestor of pool b.
! 516: * @param a The pool to search
! 517: * @param b The pool to search for
! 518: * @return True if a is an ancestor of b, NULL is considered an ancestor
! 519: * of all pools.
! 520: * @remark if compiled with APR_POOL_DEBUG, this function will also
! 521: * return true if A is a pool which has been guaranteed by the caller
! 522: * (using apr_pool_join) to have a lifetime at least as long as some
! 523: * ancestor of pool B.
! 524: */
! 525: APR_DECLARE(int) apr_pool_is_ancestor(apr_pool_t *a, apr_pool_t *b);
! 526:
! 527: /**
! 528: * Tag a pool (give it a name)
! 529: * @param pool The pool to tag
! 530: * @param tag The tag
! 531: */
! 532: APR_DECLARE(void) apr_pool_tag(apr_pool_t *pool, const char *tag)
! 533: __attribute__((nonnull(1)));
! 534:
! 535:
! 536: /*
! 537: * User data management
! 538: */
! 539:
! 540: /**
! 541: * Set the data associated with the current pool
! 542: * @param data The user data associated with the pool.
! 543: * @param key The key to use for association
! 544: * @param cleanup The cleanup program to use to cleanup the data (NULL if none)
! 545: * @param pool The current pool
! 546: * @warning The data to be attached to the pool should have a life span
! 547: * at least as long as the pool it is being attached to.
! 548: *
! 549: * Users of APR must take EXTREME care when choosing a key to
! 550: * use for their data. It is possible to accidentally overwrite
! 551: * data by choosing a key that another part of the program is using.
! 552: * Therefore it is advised that steps are taken to ensure that unique
! 553: * keys are used for all of the userdata objects in a particular pool
! 554: * (the same key in two different pools or a pool and one of its
! 555: * subpools is okay) at all times. Careful namespace prefixing of
! 556: * key names is a typical way to help ensure this uniqueness.
! 557: *
! 558: */
! 559: APR_DECLARE(apr_status_t) apr_pool_userdata_set(const void *data,
! 560: const char *key,
! 561: apr_status_t (*cleanup)(void *),
! 562: apr_pool_t *pool)
! 563: __attribute__((nonnull(2,4)));
! 564:
! 565: /**
! 566: * Set the data associated with the current pool
! 567: * @param data The user data associated with the pool.
! 568: * @param key The key to use for association
! 569: * @param cleanup The cleanup program to use to cleanup the data (NULL if none)
! 570: * @param pool The current pool
! 571: * @note same as apr_pool_userdata_set(), except that this version doesn't
! 572: * make a copy of the key (this function is useful, for example, when
! 573: * the key is a string literal)
! 574: * @warning This should NOT be used if the key could change addresses by
! 575: * any means between the apr_pool_userdata_setn() call and a
! 576: * subsequent apr_pool_userdata_get() on that key, such as if a
! 577: * static string is used as a userdata key in a DSO and the DSO could
! 578: * be unloaded and reloaded between the _setn() and the _get(). You
! 579: * MUST use apr_pool_userdata_set() in such cases.
! 580: * @warning More generally, the key and the data to be attached to the
! 581: * pool should have a life span at least as long as the pool itself.
! 582: *
! 583: */
! 584: APR_DECLARE(apr_status_t) apr_pool_userdata_setn(
! 585: const void *data, const char *key,
! 586: apr_status_t (*cleanup)(void *),
! 587: apr_pool_t *pool)
! 588: __attribute__((nonnull(2,4)));
! 589:
! 590: /**
! 591: * Return the data associated with the current pool.
! 592: * @param data The user data associated with the pool.
! 593: * @param key The key for the data to retrieve
! 594: * @param pool The current pool.
! 595: */
! 596: APR_DECLARE(apr_status_t) apr_pool_userdata_get(void **data, const char *key,
! 597: apr_pool_t *pool)
! 598: __attribute__((nonnull(1,2,3)));
! 599:
! 600:
! 601: /**
! 602: * @defgroup PoolCleanup Pool Cleanup Functions
! 603: *
! 604: * Cleanups are performed in the reverse order they were registered. That is:
! 605: * Last In, First Out. A cleanup function can safely allocate memory from
! 606: * the pool that is being cleaned up. It can also safely register additional
! 607: * cleanups which will be run LIFO, directly after the current cleanup
! 608: * terminates. Cleanups have to take caution in calling functions that
! 609: * create subpools. Subpools, created during cleanup will NOT automatically
! 610: * be cleaned up. In other words, cleanups are to clean up after themselves.
! 611: *
! 612: * @{
! 613: */
! 614:
! 615: /**
! 616: * Register a function to be called when a pool is cleared or destroyed
! 617: * @param p The pool register the cleanup with
! 618: * @param data The data to pass to the cleanup function.
! 619: * @param plain_cleanup The function to call when the pool is cleared
! 620: * or destroyed
! 621: * @param child_cleanup The function to call when a child process is about
! 622: * to exec - this function is called in the child, obviously!
! 623: */
! 624: APR_DECLARE(void) apr_pool_cleanup_register(
! 625: apr_pool_t *p, const void *data,
! 626: apr_status_t (*plain_cleanup)(void *),
! 627: apr_status_t (*child_cleanup)(void *))
! 628: __attribute__((nonnull(3,4)));
! 629:
! 630: /**
! 631: * Register a function to be called when a pool is cleared or destroyed.
! 632: *
! 633: * Unlike apr_pool_cleanup_register which register a cleanup
! 634: * that is called AFTER all subpools are destroyed this function register
! 635: * a function that will be called before any of the subpool is destoryed.
! 636: *
! 637: * @param p The pool register the cleanup with
! 638: * @param data The data to pass to the cleanup function.
! 639: * @param plain_cleanup The function to call when the pool is cleared
! 640: * or destroyed
! 641: */
! 642: APR_DECLARE(void) apr_pool_pre_cleanup_register(
! 643: apr_pool_t *p, const void *data,
! 644: apr_status_t (*plain_cleanup)(void *))
! 645: __attribute__((nonnull(3)));
! 646:
! 647: /**
! 648: * Remove a previously registered cleanup function.
! 649: *
! 650: * The cleanup most recently registered with @a p having the same values of
! 651: * @a data and @a cleanup will be removed.
! 652: *
! 653: * @param p The pool to remove the cleanup from
! 654: * @param data The data of the registered cleanup
! 655: * @param cleanup The function to remove from cleanup
! 656: * @remarks For some strange reason only the plain_cleanup is handled by this
! 657: * function
! 658: */
! 659: APR_DECLARE(void) apr_pool_cleanup_kill(apr_pool_t *p, const void *data,
! 660: apr_status_t (*cleanup)(void *))
! 661: __attribute__((nonnull(3)));
! 662:
! 663: /**
! 664: * Replace the child cleanup function of a previously registered cleanup.
! 665: *
! 666: * The cleanup most recently registered with @a p having the same values of
! 667: * @a data and @a plain_cleanup will have the registered child cleanup
! 668: * function replaced with @a child_cleanup.
! 669: *
! 670: * @param p The pool of the registered cleanup
! 671: * @param data The data of the registered cleanup
! 672: * @param plain_cleanup The plain cleanup function of the registered cleanup
! 673: * @param child_cleanup The function to register as the child cleanup
! 674: */
! 675: APR_DECLARE(void) apr_pool_child_cleanup_set(
! 676: apr_pool_t *p, const void *data,
! 677: apr_status_t (*plain_cleanup)(void *),
! 678: apr_status_t (*child_cleanup)(void *))
! 679: __attribute__((nonnull(3,4)));
! 680:
! 681: /**
! 682: * Run the specified cleanup function immediately and unregister it.
! 683: *
! 684: * The cleanup most recently registered with @a p having the same values of
! 685: * @a data and @a cleanup will be removed and @a cleanup will be called
! 686: * with @a data as the argument.
! 687: *
! 688: * @param p The pool to remove the cleanup from
! 689: * @param data The data to remove from cleanup
! 690: * @param cleanup The function to remove from cleanup
! 691: */
! 692: APR_DECLARE(apr_status_t) apr_pool_cleanup_run(apr_pool_t *p, void *data,
! 693: apr_status_t (*cleanup)(void *))
! 694: __attribute__((nonnull(3)));
! 695:
! 696: /**
! 697: * An empty cleanup function.
! 698: *
! 699: * Passed to apr_pool_cleanup_register() when no cleanup is required.
! 700: *
! 701: * @param data The data to cleanup, will not be used by this function.
! 702: */
! 703: APR_DECLARE_NONSTD(apr_status_t) apr_pool_cleanup_null(void *data);
! 704:
! 705: /**
! 706: * Run all registered child cleanups, in preparation for an exec()
! 707: * call in a forked child -- close files, etc., but *don't* flush I/O
! 708: * buffers, *don't* wait for subprocesses, and *don't* free any
! 709: * memory.
! 710: */
! 711: APR_DECLARE(void) apr_pool_cleanup_for_exec(void);
! 712:
! 713: /** @} */
! 714:
! 715: /**
! 716: * @defgroup PoolDebug Pool Debugging functions.
! 717: *
! 718: * pools have nested lifetimes -- sub_pools are destroyed when the
! 719: * parent pool is cleared. We allow certain liberties with operations
! 720: * on things such as tables (and on other structures in a more general
! 721: * sense) where we allow the caller to insert values into a table which
! 722: * were not allocated from the table's pool. The table's data will
! 723: * remain valid as long as all the pools from which its values are
! 724: * allocated remain valid.
! 725: *
! 726: * For example, if B is a sub pool of A, and you build a table T in
! 727: * pool B, then it's safe to insert data allocated in A or B into T
! 728: * (because B lives at most as long as A does, and T is destroyed when
! 729: * B is cleared/destroyed). On the other hand, if S is a table in
! 730: * pool A, it is safe to insert data allocated in A into S, but it
! 731: * is *not safe* to insert data allocated from B into S... because
! 732: * B can be cleared/destroyed before A is (which would leave dangling
! 733: * pointers in T's data structures).
! 734: *
! 735: * In general we say that it is safe to insert data into a table T
! 736: * if the data is allocated in any ancestor of T's pool. This is the
! 737: * basis on which the APR_POOL_DEBUG code works -- it tests these ancestor
! 738: * relationships for all data inserted into tables. APR_POOL_DEBUG also
! 739: * provides tools (apr_pool_find, and apr_pool_is_ancestor) for other
! 740: * folks to implement similar restrictions for their own data
! 741: * structures.
! 742: *
! 743: * However, sometimes this ancestor requirement is inconvenient --
! 744: * sometimes it's necessary to create a sub pool where the sub pool is
! 745: * guaranteed to have the same lifetime as the parent pool. This is a
! 746: * guarantee implemented by the *caller*, not by the pool code. That
! 747: * is, the caller guarantees they won't destroy the sub pool
! 748: * individually prior to destroying the parent pool.
! 749: *
! 750: * In this case the caller must call apr_pool_join() to indicate this
! 751: * guarantee to the APR_POOL_DEBUG code.
! 752: *
! 753: * These functions are only implemented when #APR_POOL_DEBUG is set.
! 754: *
! 755: * @{
! 756: */
! 757: #if APR_POOL_DEBUG || defined(DOXYGEN)
! 758: /**
! 759: * Guarantee that a subpool has the same lifetime as the parent.
! 760: * @param p The parent pool
! 761: * @param sub The subpool
! 762: */
! 763: APR_DECLARE(void) apr_pool_join(apr_pool_t *p, apr_pool_t *sub)
! 764: __attribute__((nonnull(2)));
! 765:
! 766: /**
! 767: * Find a pool from something allocated in it.
! 768: * @param mem The thing allocated in the pool
! 769: * @return The pool it is allocated in
! 770: */
! 771: APR_DECLARE(apr_pool_t *) apr_pool_find(const void *mem);
! 772:
! 773: /**
! 774: * Report the number of bytes currently in the pool
! 775: * @param p The pool to inspect
! 776: * @param recurse Recurse/include the subpools' sizes
! 777: * @return The number of bytes
! 778: */
! 779: APR_DECLARE(apr_size_t) apr_pool_num_bytes(apr_pool_t *p, int recurse)
! 780: __attribute__((nonnull(1)));
! 781:
! 782: /**
! 783: * Lock a pool
! 784: * @param pool The pool to lock
! 785: * @param flag The flag
! 786: */
! 787: APR_DECLARE(void) apr_pool_lock(apr_pool_t *pool, int flag);
! 788:
! 789: /* @} */
! 790:
! 791: #else /* APR_POOL_DEBUG or DOXYGEN */
! 792:
! 793: #ifdef apr_pool_join
! 794: #undef apr_pool_join
! 795: #endif
! 796: #define apr_pool_join(a,b)
! 797:
! 798: #ifdef apr_pool_lock
! 799: #undef apr_pool_lock
! 800: #endif
! 801: #define apr_pool_lock(pool, lock)
! 802:
! 803: #endif /* APR_POOL_DEBUG or DOXYGEN */
! 804:
! 805: /** @} */
! 806:
! 807: #ifdef __cplusplus
! 808: }
! 809: #endif
! 810:
! 811: #endif /* !APR_POOLS_H */
E-mail:
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to apr_pools.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [parser3project] / win32 / apache22 / srclib / apr / include