contrib/apr/include/apr_pools.h

   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(const apr_file_t *thefile);
  75  * </pre>
  76  * @remark Doxygen unwraps this macro (via doxygen.conf) to provide
  77  * actual help for each specific occurrence 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  *                                    pool's 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 pool's 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 created with the new pool 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  * @warning Any child cleanups registered against the new pool, or
 222  *         against sub-pools thereof, will not be executed during an
 223  *         invocation of apr_proc_create(), so resources created in an
 224  *         "unmanaged" pool hierarchy will leak to child processes.
 225  */
 226 APR_DECLARE(apr_status_t) apr_pool_create_unmanaged_ex(apr_pool_t **newpool,
 227                                                    apr_abortfunc_t abort_fn,
 228                                                    apr_allocator_t *allocator)
 229                           __attribute__((nonnull(1)));
 230
 231 /**
 232  * Debug version of apr_pool_create_ex.
 233  * @param newpool @see apr_pool_create.
 234  * @param parent @see apr_pool_create.
 235  * @param abort_fn @see apr_pool_create.
 236  * @param allocator @see apr_pool_create.
 237  * @param file_line Where the function is called from.
 238  *        This is usually APR_POOL__FILE_LINE__.
 239  * @remark Only available when APR_POOL_DEBUG is defined.
 240  *         Call this directly if you have your apr_pool_create_ex
 241  *         calls in a wrapper function and wish to override
 242  *         the file_line argument to reflect the caller of
 243  *         your wrapper function.  If you do not have
 244  *         apr_pool_create_ex in a wrapper, trust the macro
 245  *         and don't call apr_pool_create_ex_debug directly.
 246  */
 247 APR_DECLARE(apr_status_t) apr_pool_create_ex_debug(apr_pool_t **newpool,
 248                                                    apr_pool_t *parent,
 249                                                    apr_abortfunc_t abort_fn,
 250                                                    apr_allocator_t *allocator,
 251                                                    const char *file_line)
 252                           __attribute__((nonnull(1)));
 253
 254 #if APR_POOL_DEBUG
 255 #define apr_pool_create_ex(newpool, parent, abort_fn, allocator)  \
 256     apr_pool_create_ex_debug(newpool, parent, abort_fn, allocator, \
 257                              APR_POOL__FILE_LINE__)
 258 #endif
 259
 260 /**
 261  * Debug version of apr_pool_create_core_ex.
 262  * @deprecated @see apr_pool_create_unmanaged_ex_debug.
 263  */
 264 APR_DECLARE(apr_status_t) apr_pool_create_core_ex_debug(apr_pool_t **newpool,
 265                                                    apr_abortfunc_t abort_fn,
 266                                                    apr_allocator_t *allocator,
 267                                                    const char *file_line);
 268
 269 /**
 270  * Debug version of apr_pool_create_unmanaged_ex.
 271  * @param newpool @see apr_pool_create_unmanaged.
 272  * @param abort_fn @see apr_pool_create_unmanaged.
 273  * @param allocator @see apr_pool_create_unmanaged.
 274  * @param file_line Where the function is called from.
 275  *        This is usually APR_POOL__FILE_LINE__.
 276  * @remark Only available when APR_POOL_DEBUG is defined.
 277  *         Call this directly if you have your apr_pool_create_unmanaged_ex
 278  *         calls in a wrapper function and wish to override
 279  *         the file_line argument to reflect the caller of
 280  *         your wrapper function.  If you do not have
 281  *         apr_pool_create_core_ex in a wrapper, trust the macro
 282  *         and don't call apr_pool_create_core_ex_debug directly.
 283  */
 284 APR_DECLARE(apr_status_t) apr_pool_create_unmanaged_ex_debug(apr_pool_t **newpool,
 285                                                    apr_abortfunc_t abort_fn,
 286                                                    apr_allocator_t *allocator,
 287                                                    const char *file_line)
 288                           __attribute__((nonnull(1)));
 289
 290 #if APR_POOL_DEBUG
 291 #define apr_pool_create_core_ex(newpool, abort_fn, allocator)  \
 292     apr_pool_create_unmanaged_ex_debug(newpool, abort_fn, allocator, \
 293                                   APR_POOL__FILE_LINE__)
 294
 295 #define apr_pool_create_unmanaged_ex(newpool, abort_fn, allocator)  \
 296     apr_pool_create_unmanaged_ex_debug(newpool, abort_fn, allocator, \
 297                                   APR_POOL__FILE_LINE__)
 298
 299 #endif
 300
 301 /**
 302  * Create a new pool.
 303  * @param newpool The pool we have just created.
 304  * @param parent The parent pool.  If this is NULL, the new pool is a root
 305  *        pool.  If it is non-NULL, the new pool will inherit all
 306  *        of its parent pool's attributes, except the apr_pool_t will
 307  *        be a sub-pool.
 308  * @remark This function is thread-safe, in the sense that multiple threads
 309  *         can safely create subpools of the same parent pool concurrently.
 310  *         Similarly, a subpool can be created by one thread at the same
 311  *         time that another thread accesses the parent pool.
 312  */
 313 #if defined(DOXYGEN)
 314 APR_DECLARE(apr_status_t) apr_pool_create(apr_pool_t **newpool,
 315                                           apr_pool_t *parent);
 316 #else
 317 #if APR_POOL_DEBUG
 318 #define apr_pool_create(newpool, parent) \
 319     apr_pool_create_ex_debug(newpool, parent, NULL, NULL, \
 320                              APR_POOL__FILE_LINE__)
 321 #else
 322 #define apr_pool_create(newpool, parent) \
 323     apr_pool_create_ex(newpool, parent, NULL, NULL)
 324 #endif
 325 #endif
 326
 327 /**
 328  * Create a new unmanaged pool.
 329  * @param newpool The pool we have just created.
 330  */
 331 #if defined(DOXYGEN)
 332 APR_DECLARE(apr_status_t) apr_pool_create_core(apr_pool_t **newpool);
 333 APR_DECLARE(apr_status_t) apr_pool_create_unmanaged(apr_pool_t **newpool);
 334 #else
 335 #if APR_POOL_DEBUG
 336 #define apr_pool_create_core(newpool) \
 337     apr_pool_create_unmanaged_ex_debug(newpool, NULL, NULL, \
 338                                   APR_POOL__FILE_LINE__)
 339 #define apr_pool_create_unmanaged(newpool) \
 340     apr_pool_create_unmanaged_ex_debug(newpool, NULL, NULL, \
 341                                   APR_POOL__FILE_LINE__)
 342 #else
 343 #define apr_pool_create_core(newpool) \
 344     apr_pool_create_unmanaged_ex(newpool, NULL, NULL)
 345 #define apr_pool_create_unmanaged(newpool) \
 346     apr_pool_create_unmanaged_ex(newpool, NULL, NULL)
 347 #endif
 348 #endif
 349
 350 /**
 351  * Find the pool's allocator
 352  * @param pool The pool to get the allocator from.
 353  */
 354 APR_DECLARE(apr_allocator_t *) apr_pool_allocator_get(apr_pool_t *pool)
 355                                __attribute__((nonnull(1)));
 356
 357 /**
 358  * Clear all memory in the pool and run all the cleanups. This also destroys all
 359  * subpools.
 360  * @param p The pool to clear
 361  * @remark This does not actually free the memory, it just allows the pool
 362  *         to re-use this memory for the next allocation.
 363  * @see apr_pool_destroy()
 364  */
 365 APR_DECLARE(void) apr_pool_clear(apr_pool_t *p) __attribute__((nonnull(1)));
 366
 367 /**
 368  * Debug version of apr_pool_clear.
 369  * @param p See: apr_pool_clear.
 370  * @param file_line Where the function is called from.
 371  *        This is usually APR_POOL__FILE_LINE__.
 372  * @remark Only available when APR_POOL_DEBUG is defined.
 373  *         Call this directly if you have your apr_pool_clear
 374  *         calls in a wrapper function and wish to override
 375  *         the file_line argument to reflect the caller of
 376  *         your wrapper function.  If you do not have
 377  *         apr_pool_clear in a wrapper, trust the macro
 378  *         and don't call apr_pool_destroy_clear directly.
 379  */
 380 APR_DECLARE(void) apr_pool_clear_debug(apr_pool_t *p,
 381                                        const char *file_line)
 382                   __attribute__((nonnull(1)));
 383
 384 #if APR_POOL_DEBUG
 385 #define apr_pool_clear(p) \
 386     apr_pool_clear_debug(p, APR_POOL__FILE_LINE__)
 387 #endif
 388
 389 /**
 390  * Destroy the pool. This takes similar action as apr_pool_clear() and then
 391  * frees all the memory.
 392  * @param p The pool to destroy
 393  * @remark This will actually free the memory
 394  */
 395 APR_DECLARE(void) apr_pool_destroy(apr_pool_t *p) __attribute__((nonnull(1)));
 396
 397 /**
 398  * Debug version of apr_pool_destroy.
 399  * @param p See: apr_pool_destroy.
 400  * @param file_line Where the function is called from.
 401  *        This is usually APR_POOL__FILE_LINE__.
 402  * @remark Only available when APR_POOL_DEBUG is defined.
 403  *         Call this directly if you have your apr_pool_destroy
 404  *         calls in a wrapper function and wish to override
 405  *         the file_line argument to reflect the caller of
 406  *         your wrapper function.  If you do not have
 407  *         apr_pool_destroy in a wrapper, trust the macro
 408  *         and don't call apr_pool_destroy_debug directly.
 409  */
 410 APR_DECLARE(void) apr_pool_destroy_debug(apr_pool_t *p,
 411                                          const char *file_line)
 412                   __attribute__((nonnull(1)));
 413
 414 #if APR_POOL_DEBUG
 415 #define apr_pool_destroy(p) \
 416     apr_pool_destroy_debug(p, APR_POOL__FILE_LINE__)
 417 #endif
 418
 419
 420 /*
 421  * Memory allocation
 422  */
 423
 424 /**
 425  * Allocate a block of memory from a pool
 426  * @param p The pool to allocate from
 427  * @param size The amount of memory to allocate
 428  * @return The allocated memory
 429  */
 430 APR_DECLARE(void *) apr_palloc(apr_pool_t *p, apr_size_t size)
 431 #if defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4))
 432                     __attribute__((alloc_size(2)))
 433 #endif
 434                     __attribute__((nonnull(1)));
 435
 436 /**
 437  * Debug version of apr_palloc
 438  * @param p See: apr_palloc
 439  * @param size See: apr_palloc
 440  * @param file_line Where the function is called from.
 441  *        This is usually APR_POOL__FILE_LINE__.
 442  * @return See: apr_palloc
 443  */
 444 APR_DECLARE(void *) apr_palloc_debug(apr_pool_t *p, apr_size_t size,
 445                                      const char *file_line)
 446 #if defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4))
 447                     __attribute__((alloc_size(2)))
 448 #endif
 449                     __attribute__((nonnull(1)));
 450
 451 #if APR_POOL_DEBUG
 452 #define apr_palloc(p, size) \
 453     apr_palloc_debug(p, size, APR_POOL__FILE_LINE__)
 454 #endif
 455
 456 /**
 457  * Allocate a block of memory from a pool and set all of the memory to 0
 458  * @param p The pool to allocate from
 459  * @param size The amount of memory to allocate
 460  * @return The allocated memory
 461  */
 462 #if defined(DOXYGEN)
 463 APR_DECLARE(void *) apr_pcalloc(apr_pool_t *p, apr_size_t size);
 464 #elif !APR_POOL_DEBUG
 465 #define apr_pcalloc(p, size) memset(apr_palloc(p, size), 0, size)
 466 #endif
 467
 468 /**
 469  * Debug version of apr_pcalloc
 470  * @param p See: apr_pcalloc
 471  * @param size See: apr_pcalloc
 472  * @param file_line Where the function is called from.
 473  *        This is usually APR_POOL__FILE_LINE__.
 474  * @return See: apr_pcalloc
 475  */
 476 APR_DECLARE(void *) apr_pcalloc_debug(apr_pool_t *p, apr_size_t size,
 477                                       const char *file_line)
 478                     __attribute__((nonnull(1)));
 479
 480 #if APR_POOL_DEBUG
 481 #define apr_pcalloc(p, size) \
 482     apr_pcalloc_debug(p, size, APR_POOL__FILE_LINE__)
 483 #endif
 484
 485
 486 /*
 487  * Pool Properties
 488  */
 489
 490 /**
 491  * Set the function to be called when an allocation failure occurs.
 492  * @remark If the program wants APR to exit on a memory allocation error,
 493  *      then this function can be called to set the callback to use (for
 494  *      performing cleanup and then exiting). If this function is not called,
 495  *      then APR will return an error and expect the calling program to
 496  *      deal with the error accordingly.
 497  */
 498 APR_DECLARE(void) apr_pool_abort_set(apr_abortfunc_t abortfunc,
 499                                      apr_pool_t *pool)
 500                   __attribute__((nonnull(2)));
 501
 502 /**
 503  * Get the abort function associated with the specified pool.
 504  * @param pool The pool for retrieving the abort function.
 505  * @return The abort function for the given pool.
 506  */
 507 APR_DECLARE(apr_abortfunc_t) apr_pool_abort_get(apr_pool_t *pool)
 508                              __attribute__((nonnull(1)));
 509
 510 /**
 511  * Get the parent pool of the specified pool.
 512  * @param pool The pool for retrieving the parent pool.
 513  * @return The parent of the given pool.
 514  */
 515 APR_DECLARE(apr_pool_t *) apr_pool_parent_get(apr_pool_t *pool)
 516                           __attribute__((nonnull(1)));
 517
 518 /**
 519  * Determine if pool a is an ancestor of pool b.
 520  * @param a The pool to search
 521  * @param b The pool to search for
 522  * @return True if a is an ancestor of b, NULL is considered an ancestor
 523  *         of all pools.
 524  * @remark if compiled with APR_POOL_DEBUG, this function will also
 525  * return true if A is a pool which has been guaranteed by the caller
 526  * (using apr_pool_join) to have a lifetime at least as long as some
 527  * ancestor of pool B.
 528  */
 529 APR_DECLARE(int) apr_pool_is_ancestor(apr_pool_t *a, apr_pool_t *b);
 530
 531 /**
 532  * Tag a pool (give it a name)
 533  * @param pool The pool to tag
 534  * @param tag  The tag
 535  */
 536 APR_DECLARE(void) apr_pool_tag(apr_pool_t *pool, const char *tag)
 537                   __attribute__((nonnull(1)));
 538
 539
 540 /*
 541  * User data management
 542  */
 543
 544 /**
 545  * Set the data associated with the current pool
 546  * @param data The user data associated with the pool.
 547  * @param key The key to use for association
 548  * @param cleanup The cleanup program to use to cleanup the data (NULL if none)
 549  * @param pool The current pool
 550  * @warning The data to be attached to the pool should have a life span
 551  *          at least as long as the pool it is being attached to.
 552  *
 553  *      Users of APR must take EXTREME care when choosing a key to
 554  *      use for their data.  It is possible to accidentally overwrite
 555  *      data by choosing a key that another part of the program is using.
 556  *      Therefore it is advised that steps are taken to ensure that unique
 557  *      keys are used for all of the userdata objects in a particular pool
 558  *      (the same key in two different pools or a pool and one of its
 559  *      subpools is okay) at all times.  Careful namespace prefixing of
 560  *      key names is a typical way to help ensure this uniqueness.
 561  *
 562  */
 563 APR_DECLARE(apr_status_t) apr_pool_userdata_set(const void *data,
 564                                                 const char *key,
 565                                                 apr_status_t (*cleanup)(void *),
 566                                                 apr_pool_t *pool)
 567                           __attribute__((nonnull(2,4)));
 568
 569 /**
 570  * Set the data associated with the current pool
 571  * @param data The user data associated with the pool.
 572  * @param key The key to use for association
 573  * @param cleanup The cleanup program to use to cleanup the data (NULL if none)
 574  * @param pool The current pool
 575  * @note same as apr_pool_userdata_set(), except that this version doesn't
 576  *       make a copy of the key (this function is useful, for example, when
 577  *       the key is a string literal)
 578  * @warning This should NOT be used if the key could change addresses by
 579  *       any means between the apr_pool_userdata_setn() call and a
 580  *       subsequent apr_pool_userdata_get() on that key, such as if a
 581  *       static string is used as a userdata key in a DSO and the DSO could
 582  *       be unloaded and reloaded between the _setn() and the _get().  You
 583  *       MUST use apr_pool_userdata_set() in such cases.
 584  * @warning More generally, the key and the data to be attached to the
 585  *       pool should have a life span at least as long as the pool itself.
 586  *
 587  */
 588 APR_DECLARE(apr_status_t) apr_pool_userdata_setn(
 589                                 const void *data, const char *key,
 590                                 apr_status_t (*cleanup)(void *),
 591                                 apr_pool_t *pool)
 592                           __attribute__((nonnull(2,4)));
 593
 594 /**
 595  * Return the data associated with the current pool.
 596  * @param data The user data associated with the pool.
 597  * @param key The key for the data to retrieve
 598  * @param pool The current pool.
 599  */
 600 APR_DECLARE(apr_status_t) apr_pool_userdata_get(void **data, const char *key,
 601                                                 apr_pool_t *pool)
 602                           __attribute__((nonnull(1,2,3)));
 603
 604
 605 /**
 606  * @defgroup PoolCleanup  Pool Cleanup Functions
 607  *
 608  * Cleanups are performed in the reverse order they were registered.  That is:
 609  * Last In, First Out.  A cleanup function can safely allocate memory from
 610  * the pool that is being cleaned up. It can also safely register additional
 611  * cleanups which will be run LIFO, directly after the current cleanup
 612  * terminates.  Cleanups have to take caution in calling functions that
 613  * create subpools. Subpools, created during cleanup will NOT automatically
 614  * be cleaned up.  In other words, cleanups are to clean up after themselves.
 615  *
 616  * @{
 617  */
 618
 619 /**
 620  * Register a function to be called when a pool is cleared or destroyed
 621  * @param p The pool to register the cleanup with
 622  * @param data The data to pass to the cleanup function.
 623  * @param plain_cleanup The function to call when the pool is cleared
 624  *                      or destroyed
 625  * @param child_cleanup The function to call when a child process is about
 626  *                      to exec - this function is called in the child, obviously!
 627  */
 628 APR_DECLARE(void) apr_pool_cleanup_register(
 629                             apr_pool_t *p, const void *data,
 630                             apr_status_t (*plain_cleanup)(void *),
 631                             apr_status_t (*child_cleanup)(void *))
 632                   __attribute__((nonnull(3,4)));
 633
 634 /**
 635  * Register a function to be called when a pool is cleared or destroyed.
 636  *
 637  * Unlike apr_pool_cleanup_register which registers a cleanup
 638  * that is called AFTER all subpools are destroyed, this function registers
 639  * a function that will be called before any of the subpools are destroyed.
 640  *
 641  * @param p The pool to register the cleanup with
 642  * @param data The data to pass to the cleanup function.
 643  * @param plain_cleanup The function to call when the pool is cleared
 644  *                      or destroyed
 645  */
 646 APR_DECLARE(void) apr_pool_pre_cleanup_register(
 647                             apr_pool_t *p, const void *data,
 648                             apr_status_t (*plain_cleanup)(void *))
 649                   __attribute__((nonnull(3)));
 650
 651 /**
 652  * Remove a previously registered cleanup function.
 653  *
 654  * The cleanup most recently registered with @a p having the same values of
 655  * @a data and @a cleanup will be removed.
 656  *
 657  * @param p The pool to remove the cleanup from
 658  * @param data The data of the registered cleanup
 659  * @param cleanup The function to remove from cleanup
 660  * @remarks For some strange reason only the plain_cleanup is handled by this
 661  *          function
 662  */
 663 APR_DECLARE(void) apr_pool_cleanup_kill(apr_pool_t *p, const void *data,
 664                                         apr_status_t (*cleanup)(void *))
 665                   __attribute__((nonnull(3)));
 666
 667 /**
 668  * Replace the child cleanup function of a previously registered cleanup.
 669  *
 670  * The cleanup most recently registered with @a p having the same values of
 671  * @a data and @a plain_cleanup will have the registered child cleanup
 672  * function replaced with @a child_cleanup.
 673  *
 674  * @param p The pool of the registered cleanup
 675  * @param data The data of the registered cleanup
 676  * @param plain_cleanup The plain cleanup function of the registered cleanup
 677  * @param child_cleanup The function to register as the child cleanup
 678  */
 679 APR_DECLARE(void) apr_pool_child_cleanup_set(
 680                         apr_pool_t *p, const void *data,
 681                         apr_status_t (*plain_cleanup)(void *),
 682                         apr_status_t (*child_cleanup)(void *))
 683                   __attribute__((nonnull(3,4)));
 684
 685 /**
 686  * Run the specified cleanup function immediately and unregister it.
 687  *
 688  * The cleanup most recently registered with @a p having the same values of
 689  * @a data and @a cleanup will be removed and @a cleanup will be called
 690  * with @a data as the argument.
 691  *
 692  * @param p The pool to remove the cleanup from
 693  * @param data The data to remove from cleanup
 694  * @param cleanup The function to remove from cleanup
 695  */
 696 APR_DECLARE(apr_status_t) apr_pool_cleanup_run(apr_pool_t *p, void *data,
 697                                                apr_status_t (*cleanup)(void *))
 698                           __attribute__((nonnull(3)));
 699
 700 /**
 701  * An empty cleanup function.
 702  *
 703  * Passed to apr_pool_cleanup_register() when no cleanup is required.
 704  *
 705  * @param data The data to cleanup, will not be used by this function.
 706  */
 707 APR_DECLARE_NONSTD(apr_status_t) apr_pool_cleanup_null(void *data);
 708
 709 /**
 710  * Run all registered child cleanups, in preparation for an exec()
 711  * call in a forked child -- close files, etc., but *don't* flush I/O
 712  * buffers, *don't* wait for subprocesses, and *don't* free any
 713  * memory.
 714  */
 715 APR_DECLARE(void) apr_pool_cleanup_for_exec(void);
 716
 717 /** @} */
 718
 719 /**
 720  * @defgroup PoolDebug Pool Debugging functions.
 721  *
 722  * pools have nested lifetimes -- sub_pools are destroyed when the
 723  * parent pool is cleared.  We allow certain liberties with operations
 724  * on things such as tables (and on other structures in a more general
 725  * sense) where we allow the caller to insert values into a table which
 726  * were not allocated from the table's pool.  The table's data will
 727  * remain valid as long as all the pools from which its values are
 728  * allocated remain valid.
 729  *
 730  * For example, if B is a sub pool of A, and you build a table T in
 731  * pool B, then it's safe to insert data allocated in A or B into T
 732  * (because B lives at most as long as A does, and T is destroyed when
 733  * B is cleared/destroyed).  On the other hand, if S is a table in
 734  * pool A, it is safe to insert data allocated in A into S, but it
 735  * is *not safe* to insert data allocated from B into S... because
 736  * B can be cleared/destroyed before A is (which would leave dangling
 737  * pointers in T's data structures).
 738  *
 739  * In general we say that it is safe to insert data into a table T
 740  * if the data is allocated in any ancestor of T's pool.  This is the
 741  * basis on which the APR_POOL_DEBUG code works -- it tests these ancestor
 742  * relationships for all data inserted into tables.  APR_POOL_DEBUG also
 743  * provides tools (apr_pool_find, and apr_pool_is_ancestor) for other
 744  * folks to implement similar restrictions for their own data
 745  * structures.
 746  *
 747  * However, sometimes this ancestor requirement is inconvenient --
 748  * sometimes it's necessary to create a sub pool where the sub pool is
 749  * guaranteed to have the same lifetime as the parent pool.  This is a
 750  * guarantee implemented by the *caller*, not by the pool code.  That
 751  * is, the caller guarantees they won't destroy the sub pool
 752  * individually prior to destroying the parent pool.
 753  *
 754  * In this case the caller must call apr_pool_join() to indicate this
 755  * guarantee to the APR_POOL_DEBUG code.
 756  *
 757  * These functions are only implemented when #APR_POOL_DEBUG is set.
 758  *
 759  * @{
 760  */
 761 #if APR_POOL_DEBUG || defined(DOXYGEN)
 762 /**
 763  * Guarantee that a subpool has the same lifetime as the parent.
 764  * @param p The parent pool
 765  * @param sub The subpool
 766  */
 767 APR_DECLARE(void) apr_pool_join(apr_pool_t *p, apr_pool_t *sub)
 768                   __attribute__((nonnull(2)));
 769
 770 /**
 771  * Find a pool from something allocated in it.
 772  * @param mem The thing allocated in the pool
 773  * @return The pool it is allocated in
 774  */
 775 APR_DECLARE(apr_pool_t *) apr_pool_find(const void *mem);
 776
 777 /**
 778  * Report the number of bytes currently in the pool
 779  * @param p The pool to inspect
 780  * @param recurse Recurse/include the subpools' sizes
 781  * @return The number of bytes
 782  */
 783 APR_DECLARE(apr_size_t) apr_pool_num_bytes(apr_pool_t *p, int recurse)
 784                         __attribute__((nonnull(1)));
 785
 786 /**
 787  * Lock a pool
 788  * @param pool The pool to lock
 789  * @param flag  The flag
 790  */
 791 APR_DECLARE(void) apr_pool_lock(apr_pool_t *pool, int flag);
 792
 793 /* @} */
 794
 795 #else /* APR_POOL_DEBUG or DOXYGEN */
 796
 797 #ifdef apr_pool_join
 798 #undef apr_pool_join
 799 #endif
 800 #define apr_pool_join(a,b)
 801
 802 #ifdef apr_pool_lock
 803 #undef apr_pool_lock
 804 #endif
 805 #define apr_pool_lock(pool, lock)
 806
 807 #endif /* APR_POOL_DEBUG or DOXYGEN */
 808
 809 /** @} */
 810
 811 #ifdef __cplusplus
 812 }
 813 #endif
 814
 815 #endif /* !APR_POOLS_H */