#$@%#$%!

Ngiler SH3LL 360
: / opt / cpanel / ea-apr16 / include / apr-1 /

Information Server
MySQL : OFF Perl : OFF CURL : ON WGET : OFF PKEXEC : OFF

Directive	Local Value
IP Address	162.0.209.101
System	Linux premium169.web-hosting.com 4.18.0-553.50.1.lve.el8.x86_64 #1 SMP Thu Apr 17 19:10:24 UTC 2025 x86_64
User	luxeelil
PHP Version	8.0.30
Software	LiteSpeed
Doc root	Writable

Edit File : apr_pools.h \| Size : 30.94 KB
/* Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. / #ifndef APR_POOLS_H #define APR_POOLS_H /* * @file apr_pools.h * @brief APR memory allocation * * Resource allocation routines... * * designed so that we don't have to keep track of EVERYTHING so that * it can be explicitly freed later (a fundamentally unsound strategy --- * particularly in the presence of die()). * * Instead, we maintain pools, and allocate items (both memory and I/O * handlers) from the pools --- currently there are two, one for * per-transaction info, and one for config info. When a transaction is * over, we can delete everything in the per-transaction apr_pool_t without * fear, and without thinking too hard about it either. * * Note that most operations on pools are not thread-safe: a single pool * should only be accessed by a single thread at any given time. The one * exception to this rule is creating a subpool of a given pool: one or more * threads can safely create subpools at the same time that another thread * accesses the parent pool. / #include "apr.h" #include "apr_errno.h" #include "apr_general.h" / for APR_STRINGIFY / #define APR_WANT_MEMFUNC /< for no good reason? / #include "apr_want.h" #ifdef __cplusplus extern "C" { #endif /** * @defgroup apr_pools Memory Pool Functions * @ingroup APR * @{ / /* The fundamental pool type / typedef struct apr_pool_t apr_pool_t; /* * Declaration helper macro to construct apr_foo_pool_get()s. * * This standardized macro is used by opaque (APR) data types to return * the apr_pool_t that is associated with the data type. * * APR_POOL_DECLARE_ACCESSOR() is used in a header file to declare the * accessor function. A typical usage and result would be: * <pre> * APR_POOL_DECLARE_ACCESSOR(file); * becomes: * APR_DECLARE(apr_pool_t ) apr_file_pool_get(const apr_file_t thefile); * </pre> * @remark Doxygen unwraps this macro (via doxygen.conf) to provide * actual help for each specific occurrence of apr_foo_pool_get. * @remark the linkage is specified for APR. It would be possible to expand * the macros to support other linkages. / #define APR_POOL_DECLARE_ACCESSOR(type) \ APR_DECLARE(apr_pool_t ) apr_##type##_pool_get \ (const apr_##type##_t the##type) /* * Implementation helper macro to provide apr_foo_pool_get()s. * * In the implementation, the APR_POOL_IMPLEMENT_ACCESSOR() is used to * actually define the function. It assumes the field is named "pool". / #define APR_POOL_IMPLEMENT_ACCESSOR(type) \ APR_DECLARE(apr_pool_t ) apr_##type##_pool_get \ (const apr_##type##_t the##type) \ { return the##type->pool; } /* * Pool debug levels * * <pre> * \| 7 \| 6 \| 5 \| 4 \| 3 \| 2 \| 1 \| 0 \| * --------------------------------- * \| \| \| \| \| \| \| \| x \| General debug code enabled (useful in * combination with --with-efence). * * \| \| \| \| \| \| \| x \| \| Verbose output on stderr (report * CREATE, CLEAR, DESTROY). * * \| \| \| \| x \| \| \| \| \| Verbose output on stderr (report * PALLOC, PCALLOC). * * \| \| \| \| \| \| x \| \| \| Lifetime checking. On each use of a * pool, check its lifetime. If the pool * is out of scope, abort(). * In combination with the verbose flag * above, it will output LIFE in such an * event prior to aborting. * * \| \| \| \| \| x \| \| \| \| Pool owner checking. On each use of a * pool, check if the current thread is the * pool's owner. If not, abort(). In * combination with the verbose flag above, * it will output OWNER in such an event * prior to aborting. Use the debug * function apr_pool_owner_set() to switch * a pool's ownership. * * When no debug level was specified, assume general debug mode. * If level 0 was specified, debugging is switched off. * </pre> / #if defined(APR_POOL_DEBUG) / If APR_POOL_DEBUG is blank, we get 1; if it is a number, we get -1. / #if (APR_POOL_DEBUG - APR_POOL_DEBUG -1 == 1) #undef APR_POOL_DEBUG #define APR_POOL_DEBUG 1 #endif #else #define APR_POOL_DEBUG 0 #endif /* the place in the code where the particular function was called / #define APR_POOL__FILE_LINE__ __FILE__ ":" APR_STRINGIFY(__LINE__) /* A function that is called when allocation fails. / typedef int (apr_abortfunc_t)(int retcode); /* * APR memory structure manipulators (pools, tables, and arrays). / / * Initialization / /* * Setup all of the internal structures required to use pools * @remark Programs do NOT need to call this directly. APR will call this * automatically from apr_initialize. * @internal / APR_DECLARE(apr_status_t) apr_pool_initialize(void); /* * Tear down all of the internal structures required to use pools * @remark Programs do NOT need to call this directly. APR will call this * automatically from apr_terminate. * @internal / APR_DECLARE(void) apr_pool_terminate(void); / * Pool creation/destruction / #include "apr_allocator.h" /* * Create a new pool. * @param newpool The pool we have just created. * @param parent The parent pool. If this is NULL, the new pool is a root * pool. If it is non-NULL, the new pool will inherit all * of its parent pool's attributes, except the apr_pool_t will * be a sub-pool. * @param abort_fn A function to use if the pool cannot allocate more memory. * @param allocator The allocator to use with the new pool. If NULL the * allocator of the parent pool will be used. * @remark This function is thread-safe, in the sense that multiple threads * can safely create subpools of the same parent pool concurrently. * Similarly, a subpool can be created by one thread at the same * time that another thread accesses the parent pool. / APR_DECLARE(apr_status_t) apr_pool_create_ex(apr_pool_t newpool, apr_pool_t parent, apr_abortfunc_t abort_fn, apr_allocator_t allocator) __attribute__((nonnull(1))); /* * Create a new pool. * @deprecated @see apr_pool_create_unmanaged_ex. / APR_DECLARE(apr_status_t) apr_pool_create_core_ex(apr_pool_t newpool, apr_abortfunc_t abort_fn, apr_allocator_t allocator); /** * Create a new unmanaged pool. * @param newpool The pool we have just created. * @param abort_fn A function to use if the pool cannot allocate more memory. * @param allocator The allocator to use with the new pool. If NULL a * new allocator will be created with the new pool as owner. * @remark An unmanaged pool is a special pool without a parent; it will * NOT be destroyed upon apr_terminate. It must be explicitly * destroyed by calling apr_pool_destroy, to prevent memory leaks. * Use of this function is discouraged, think twice about whether * you really really need it. * @warning Any child cleanups registered against the new pool, or * against sub-pools thereof, will not be executed during an * invocation of apr_proc_create(), so resources created in an * "unmanaged" pool hierarchy will leak to child processes. / APR_DECLARE(apr_status_t) apr_pool_create_unmanaged_ex(apr_pool_t newpool, apr_abortfunc_t abort_fn, apr_allocator_t allocator) __attribute__((nonnull(1))); /** * Debug version of apr_pool_create_ex. * @param newpool @see apr_pool_create. * @param parent @see apr_pool_create. * @param abort_fn @see apr_pool_create. * @param allocator @see apr_pool_create. * @param file_line Where the function is called from. * This is usually APR_POOL__FILE_LINE__. * @remark Only available when APR_POOL_DEBUG is defined. * Call this directly if you have your apr_pool_create_ex * calls in a wrapper function and wish to override * the file_line argument to reflect the caller of * your wrapper function. If you do not have * apr_pool_create_ex in a wrapper, trust the macro * and don't call apr_pool_create_ex_debug directly. / APR_DECLARE(apr_status_t) apr_pool_create_ex_debug(apr_pool_t newpool, apr_pool_t parent, apr_abortfunc_t abort_fn, apr_allocator_t allocator, const char file_line) __attribute__((nonnull(1))); #if APR_POOL_DEBUG #define apr_pool_create_ex(newpool, parent, abort_fn, allocator) \ apr_pool_create_ex_debug(newpool, parent, abort_fn, allocator, \ APR_POOL__FILE_LINE__) #endif /** * Debug version of apr_pool_create_core_ex. * @deprecated @see apr_pool_create_unmanaged_ex_debug. / APR_DECLARE(apr_status_t) apr_pool_create_core_ex_debug(apr_pool_t newpool, apr_abortfunc_t abort_fn, apr_allocator_t allocator, const char file_line); /* * Debug version of apr_pool_create_unmanaged_ex. * @param newpool @see apr_pool_create_unmanaged. * @param abort_fn @see apr_pool_create_unmanaged. * @param allocator @see apr_pool_create_unmanaged. * @param file_line Where the function is called from. * This is usually APR_POOL__FILE_LINE__. * @remark Only available when APR_POOL_DEBUG is defined. * Call this directly if you have your apr_pool_create_unmanaged_ex * calls in a wrapper function and wish to override * the file_line argument to reflect the caller of * your wrapper function. If you do not have * apr_pool_create_core_ex in a wrapper, trust the macro * and don't call apr_pool_create_core_ex_debug directly. / APR_DECLARE(apr_status_t) apr_pool_create_unmanaged_ex_debug(apr_pool_t newpool, apr_abortfunc_t abort_fn, apr_allocator_t allocator, const char file_line) __attribute__((nonnull(1))); #if APR_POOL_DEBUG #define apr_pool_create_core_ex(newpool, abort_fn, allocator) \ apr_pool_create_unmanaged_ex_debug(newpool, abort_fn, allocator, \ APR_POOL__FILE_LINE__) #define apr_pool_create_unmanaged_ex(newpool, abort_fn, allocator) \ apr_pool_create_unmanaged_ex_debug(newpool, abort_fn, allocator, \ APR_POOL__FILE_LINE__) #endif /* * Create a new pool. * @param newpool The pool we have just created. * @param parent The parent pool. If this is NULL, the new pool is a root * pool. If it is non-NULL, the new pool will inherit all * of its parent pool's attributes, except the apr_pool_t will * be a sub-pool. * @remark This function is thread-safe, in the sense that multiple threads * can safely create subpools of the same parent pool concurrently. * Similarly, a subpool can be created by one thread at the same * time that another thread accesses the parent pool. / #if defined(DOXYGEN) APR_DECLARE(apr_status_t) apr_pool_create(apr_pool_t newpool, apr_pool_t parent); #else #if APR_POOL_DEBUG #define apr_pool_create(newpool, parent) \ apr_pool_create_ex_debug(newpool, parent, NULL, NULL, \ APR_POOL__FILE_LINE__) #else #define apr_pool_create(newpool, parent) \ apr_pool_create_ex(newpool, parent, NULL, NULL) #endif #endif /** * Create a new unmanaged pool. * @param newpool The pool we have just created. / #if defined(DOXYGEN) APR_DECLARE(apr_status_t) apr_pool_create_core(apr_pool_t newpool); APR_DECLARE(apr_status_t) apr_pool_create_unmanaged(apr_pool_t newpool); #else #if APR_POOL_DEBUG #define apr_pool_create_core(newpool) \ apr_pool_create_unmanaged_ex_debug(newpool, NULL, NULL, \ APR_POOL__FILE_LINE__) #define apr_pool_create_unmanaged(newpool) \ apr_pool_create_unmanaged_ex_debug(newpool, NULL, NULL, \ APR_POOL__FILE_LINE__) #else #define apr_pool_create_core(newpool) \ apr_pool_create_unmanaged_ex(newpool, NULL, NULL) #define apr_pool_create_unmanaged(newpool) \ apr_pool_create_unmanaged_ex(newpool, NULL, NULL) #endif #endif /* * Find the pool's allocator * @param pool The pool to get the allocator from. / APR_DECLARE(apr_allocator_t ) apr_pool_allocator_get(apr_pool_t pool) __attribute__((nonnull(1))); /* * Clear all memory in the pool and run all the cleanups. This also destroys all * subpools. * @param p The pool to clear * @remark This does not actually free the memory, it just allows the pool * to re-use this memory for the next allocation. * @see apr_pool_destroy() / APR_DECLARE(void) apr_pool_clear(apr_pool_t p) __attribute__((nonnull(1))); /** * Debug version of apr_pool_clear. * @param p See: apr_pool_clear. * @param file_line Where the function is called from. * This is usually APR_POOL__FILE_LINE__. * @remark Only available when APR_POOL_DEBUG is defined. * Call this directly if you have your apr_pool_clear * calls in a wrapper function and wish to override * the file_line argument to reflect the caller of * your wrapper function. If you do not have * apr_pool_clear in a wrapper, trust the macro * and don't call apr_pool_destroy_clear directly. / APR_DECLARE(void) apr_pool_clear_debug(apr_pool_t p, const char file_line) __attribute__((nonnull(1))); #if APR_POOL_DEBUG #define apr_pool_clear(p) \ apr_pool_clear_debug(p, APR_POOL__FILE_LINE__) #endif /* * Destroy the pool. This takes similar action as apr_pool_clear() and then * frees all the memory. * @param p The pool to destroy * @remark This will actually free the memory / APR_DECLARE(void) apr_pool_destroy(apr_pool_t p) __attribute__((nonnull(1))); /** * Debug version of apr_pool_destroy. * @param p See: apr_pool_destroy. * @param file_line Where the function is called from. * This is usually APR_POOL__FILE_LINE__. * @remark Only available when APR_POOL_DEBUG is defined. * Call this directly if you have your apr_pool_destroy * calls in a wrapper function and wish to override * the file_line argument to reflect the caller of * your wrapper function. If you do not have * apr_pool_destroy in a wrapper, trust the macro * and don't call apr_pool_destroy_debug directly. / APR_DECLARE(void) apr_pool_destroy_debug(apr_pool_t p, const char file_line) __attribute__((nonnull(1))); #if APR_POOL_DEBUG #define apr_pool_destroy(p) \ apr_pool_destroy_debug(p, APR_POOL__FILE_LINE__) #endif / * Memory allocation / /* * Allocate a block of memory from a pool * @param p The pool to allocate from * @param size The amount of memory to allocate * @return The allocated memory / APR_DECLARE(void ) apr_palloc(apr_pool_t p, apr_size_t size) #if defined(__GNUC__) && (__GNUC__ > 4 \|\| (__GNUC__ == 4 && __GNUC_MINOR__ >= 4)) __attribute__((alloc_size(2))) #endif __attribute__((nonnull(1))); /* * Debug version of apr_palloc * @param p See: apr_palloc * @param size See: apr_palloc * @param file_line Where the function is called from. * This is usually APR_POOL__FILE_LINE__. * @return See: apr_palloc / APR_DECLARE(void ) apr_palloc_debug(apr_pool_t p, apr_size_t size, const char file_line) #if defined(__GNUC__) && (__GNUC__ > 4 \|\| (__GNUC__ == 4 && __GNUC_MINOR__ >= 4)) __attribute__((alloc_size(2))) #endif __attribute__((nonnull(1))); #if APR_POOL_DEBUG #define apr_palloc(p, size) \ apr_palloc_debug(p, size, APR_POOL__FILE_LINE__) #endif /** * Allocate a block of memory from a pool and set all of the memory to 0 * @param p The pool to allocate from * @param size The amount of memory to allocate * @return The allocated memory / #if defined(DOXYGEN) APR_DECLARE(void ) apr_pcalloc(apr_pool_t p, apr_size_t size); #elif !APR_POOL_DEBUG #define apr_pcalloc(p, size) memset(apr_palloc(p, size), 0, size) #endif /* * Debug version of apr_pcalloc * @param p See: apr_pcalloc * @param size See: apr_pcalloc * @param file_line Where the function is called from. * This is usually APR_POOL__FILE_LINE__. * @return See: apr_pcalloc / APR_DECLARE(void ) apr_pcalloc_debug(apr_pool_t p, apr_size_t size, const char file_line) __attribute__((nonnull(1))); #if APR_POOL_DEBUG #define apr_pcalloc(p, size) \ apr_pcalloc_debug(p, size, APR_POOL__FILE_LINE__) #endif /* * Pool Properties / /* * Set the function to be called when an allocation failure occurs. * @remark If the program wants APR to exit on a memory allocation error, * then this function can be called to set the callback to use (for * performing cleanup and then exiting). If this function is not called, * then APR will return an error and expect the calling program to * deal with the error accordingly. / APR_DECLARE(void) apr_pool_abort_set(apr_abortfunc_t abortfunc, apr_pool_t pool) __attribute__((nonnull(2))); /** * Get the abort function associated with the specified pool. * @param pool The pool for retrieving the abort function. * @return The abort function for the given pool. / APR_DECLARE(apr_abortfunc_t) apr_pool_abort_get(apr_pool_t pool) __attribute__((nonnull(1))); /** * Get the parent pool of the specified pool. * @param pool The pool for retrieving the parent pool. * @return The parent of the given pool. / APR_DECLARE(apr_pool_t ) apr_pool_parent_get(apr_pool_t pool) __attribute__((nonnull(1))); /* * Determine if pool a is an ancestor of pool b. * @param a The pool to search * @param b The pool to search for * @return True if a is an ancestor of b, NULL is considered an ancestor * of all pools. * @remark if compiled with APR_POOL_DEBUG, this function will also * return true if A is a pool which has been guaranteed by the caller * (using apr_pool_join) to have a lifetime at least as long as some * ancestor of pool B. / APR_DECLARE(int) apr_pool_is_ancestor(apr_pool_t a, apr_pool_t b); /* * Tag a pool (give it a name) * @param pool The pool to tag * @param tag The tag / APR_DECLARE(void) apr_pool_tag(apr_pool_t pool, const char tag) __attribute__((nonnull(1))); / * User data management / /* * Set the data associated with the current pool * @param data The user data associated with the pool. * @param key The key to use for association * @param cleanup The cleanup program to use to cleanup the data (NULL if none) * @param pool The current pool * @warning The data to be attached to the pool should have a life span * at least as long as the pool it is being attached to. * * Users of APR must take EXTREME care when choosing a key to * use for their data. It is possible to accidentally overwrite * data by choosing a key that another part of the program is using. * Therefore it is advised that steps are taken to ensure that unique * keys are used for all of the userdata objects in a particular pool * (the same key in two different pools or a pool and one of its * subpools is okay) at all times. Careful namespace prefixing of * key names is a typical way to help ensure this uniqueness. * / APR_DECLARE(apr_status_t) apr_pool_userdata_set(const void data, const char key, apr_status_t (cleanup)(void ), apr_pool_t pool) __attribute__((nonnull(2,4))); /** * Set the data associated with the current pool * @param data The user data associated with the pool. * @param key The key to use for association * @param cleanup The cleanup program to use to cleanup the data (NULL if none) * @param pool The current pool * @note same as apr_pool_userdata_set(), except that this version doesn't * make a copy of the key (this function is useful, for example, when * the key is a string literal) * @warning This should NOT be used if the key could change addresses by * any means between the apr_pool_userdata_setn() call and a * subsequent apr_pool_userdata_get() on that key, such as if a * static string is used as a userdata key in a DSO and the DSO could * be unloaded and reloaded between the _setn() and the _get(). You * MUST use apr_pool_userdata_set() in such cases. * @warning More generally, the key and the data to be attached to the * pool should have a life span at least as long as the pool itself. * / APR_DECLARE(apr_status_t) apr_pool_userdata_setn( const void data, const char key, apr_status_t (cleanup)(void ), apr_pool_t pool) __attribute__((nonnull(2,4))); /** * Return the data associated with the current pool. * @param data The user data associated with the pool. * @param key The key for the data to retrieve * @param pool The current pool. / APR_DECLARE(apr_status_t) apr_pool_userdata_get(void data, const char key, apr_pool_t pool) __attribute__((nonnull(1,2,3))); /* * @defgroup PoolCleanup Pool Cleanup Functions * * Cleanups are performed in the reverse order they were registered. That is: * Last In, First Out. A cleanup function can safely allocate memory from * the pool that is being cleaned up. It can also safely register additional * cleanups which will be run LIFO, directly after the current cleanup * terminates. Cleanups have to take caution in calling functions that * create subpools. Subpools, created during cleanup will NOT automatically * be cleaned up. In other words, cleanups are to clean up after themselves. * * @{ / /* * Register a function to be called when a pool is cleared or destroyed * @param p The pool to register the cleanup with * @param data The data to pass to the cleanup function. * @param plain_cleanup The function to call when the pool is cleared * or destroyed * @param child_cleanup The function to call when a child process is about * to exec - this function is called in the child, obviously! / APR_DECLARE(void) apr_pool_cleanup_register( apr_pool_t p, const void data, apr_status_t (plain_cleanup)(void ), apr_status_t (child_cleanup)(void )) __attribute__((nonnull(3,4))); /* * Register a function to be called when a pool is cleared or destroyed. * * Unlike apr_pool_cleanup_register which registers a cleanup * that is called AFTER all subpools are destroyed, this function registers * a function that will be called before any of the subpools are destroyed. * * @param p The pool to register the cleanup with * @param data The data to pass to the cleanup function. * @param plain_cleanup The function to call when the pool is cleared * or destroyed / APR_DECLARE(void) apr_pool_pre_cleanup_register( apr_pool_t p, const void data, apr_status_t (plain_cleanup)(void )) __attribute__((nonnull(3))); /* * Remove a previously registered cleanup function. * * The cleanup most recently registered with @a p having the same values of * @a data and @a cleanup will be removed. * * @param p The pool to remove the cleanup from * @param data The data of the registered cleanup * @param cleanup The function to remove from cleanup * @remarks For some strange reason only the plain_cleanup is handled by this * function / APR_DECLARE(void) apr_pool_cleanup_kill(apr_pool_t p, const void data, apr_status_t (cleanup)(void )) __attribute__((nonnull(3))); /* * Replace the child cleanup function of a previously registered cleanup. * * The cleanup most recently registered with @a p having the same values of * @a data and @a plain_cleanup will have the registered child cleanup * function replaced with @a child_cleanup. * * @param p The pool of the registered cleanup * @param data The data of the registered cleanup * @param plain_cleanup The plain cleanup function of the registered cleanup * @param child_cleanup The function to register as the child cleanup / APR_DECLARE(void) apr_pool_child_cleanup_set( apr_pool_t p, const void data, apr_status_t (plain_cleanup)(void ), apr_status_t (child_cleanup)(void )) __attribute__((nonnull(3,4))); /* * Run the specified cleanup function immediately and unregister it. * * The cleanup most recently registered with @a p having the same values of * @a data and @a cleanup will be removed and @a cleanup will be called * with @a data as the argument. * * @param p The pool to remove the cleanup from * @param data The data to remove from cleanup * @param cleanup The function to remove from cleanup / APR_DECLARE(apr_status_t) apr_pool_cleanup_run(apr_pool_t p, void data, apr_status_t (cleanup)(void )) __attribute__((nonnull(3))); /* * An empty cleanup function. * * Passed to apr_pool_cleanup_register() when no cleanup is required. * * @param data The data to cleanup, will not be used by this function. / APR_DECLARE_NONSTD(apr_status_t) apr_pool_cleanup_null(void data); /** * Run all registered child cleanups, in preparation for an exec() * call in a forked child -- close files, etc., but don't flush I/O * buffers, don't wait for subprocesses, and don't free any * memory. / APR_DECLARE(void) apr_pool_cleanup_for_exec(void); /* @} / /* * @defgroup PoolDebug Pool Debugging functions * * pools have nested lifetimes -- sub_pools are destroyed when the * parent pool is cleared. We allow certain liberties with operations * on things such as tables (and on other structures in a more general * sense) where we allow the caller to insert values into a table which * were not allocated from the table's pool. The table's data will * remain valid as long as all the pools from which its values are * allocated remain valid. * * For example, if B is a sub pool of A, and you build a table T in * pool B, then it's safe to insert data allocated in A or B into T * (because B lives at most as long as A does, and T is destroyed when * B is cleared/destroyed). On the other hand, if S is a table in * pool A, it is safe to insert data allocated in A into S, but it * is not safe to insert data allocated from B into S... because * B can be cleared/destroyed before A is (which would leave dangling * pointers in T's data structures). * * In general we say that it is safe to insert data into a table T * if the data is allocated in any ancestor of T's pool. This is the * basis on which the APR_POOL_DEBUG code works -- it tests these ancestor * relationships for all data inserted into tables. APR_POOL_DEBUG also * provides tools (apr_pool_find, and apr_pool_is_ancestor) for other * folks to implement similar restrictions for their own data * structures. * * However, sometimes this ancestor requirement is inconvenient -- * sometimes it's necessary to create a sub pool where the sub pool is * guaranteed to have the same lifetime as the parent pool. This is a * guarantee implemented by the caller, not by the pool code. That * is, the caller guarantees they won't destroy the sub pool * individually prior to destroying the parent pool. * * In this case the caller must call apr_pool_join() to indicate this * guarantee to the APR_POOL_DEBUG code. * * These functions are only implemented when #APR_POOL_DEBUG is set. * * @{ / #if APR_POOL_DEBUG \|\| defined(DOXYGEN) /* * Guarantee that a subpool has the same lifetime as the parent. * @param p The parent pool * @param sub The subpool / APR_DECLARE(void) apr_pool_join(apr_pool_t p, apr_pool_t sub) __attribute__((nonnull(2))); /* * Find a pool from something allocated in it. * @param mem The thing allocated in the pool * @return The pool it is allocated in / APR_DECLARE(apr_pool_t ) apr_pool_find(const void mem); /* * Report the number of bytes currently in the pool * @param p The pool to inspect * @param recurse Recurse/include the subpools' sizes * @return The number of bytes / APR_DECLARE(apr_size_t) apr_pool_num_bytes(apr_pool_t p, int recurse) __attribute__((nonnull(1))); /** * Lock a pool * @param pool The pool to lock * @param flag The flag / APR_DECLARE(void) apr_pool_lock(apr_pool_t pool, int flag); /** @} / #else / APR_POOL_DEBUG or DOXYGEN / #ifdef apr_pool_join #undef apr_pool_join #endif #define apr_pool_join(a,b) #ifdef apr_pool_lock #undef apr_pool_lock #endif #define apr_pool_lock(pool, lock) #endif / APR_POOL_DEBUG or DOXYGEN / /* @} / #ifdef __cplusplus } #endif #endif / !APR_POOLS_H */ Back

Edit File : apr_pools.h | Size : 30.94 KB

/* Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef APR_POOLS_H
#define APR_POOLS_H

/**
 * @file apr_pools.h
 * @brief APR memory allocation
 *
 * Resource allocation routines...
 *
 * designed so that we don't have to keep track of EVERYTHING so that
 * it can be explicitly freed later (a fundamentally unsound strategy ---
 * particularly in the presence of die()).
 *
 * Instead, we maintain pools, and allocate items (both memory and I/O
 * handlers) from the pools --- currently there are two, one for
 * per-transaction info, and one for config info.  When a transaction is
 * over, we can delete everything in the per-transaction apr_pool_t without
 * fear, and without thinking too hard about it either.
 *
 * Note that most operations on pools are not thread-safe: a single pool
 * should only be accessed by a single thread at any given time. The one
 * exception to this rule is creating a subpool of a given pool: one or more
 * threads can safely create subpools at the same time that another thread
 * accesses the parent pool.
 */

#include "apr.h"
#include "apr_errno.h"
#include "apr_general.h" /* for APR_STRINGIFY */
#define APR_WANT_MEMFUNC /**< for no good reason? */
#include "apr_want.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @defgroup apr_pools Memory Pool Functions
 * @ingroup APR 
 * @{
 */

/** The fundamental pool type */
typedef struct apr_pool_t apr_pool_t;

/**
 * Declaration helper macro to construct apr_foo_pool_get()s.
 *
 * This standardized macro is used by opaque (APR) data types to return
 * the apr_pool_t that is associated with the data type.
 *
 * APR_POOL_DECLARE_ACCESSOR() is used in a header file to declare the
 * accessor function. A typical usage and result would be:
 * <pre>
 *    APR_POOL_DECLARE_ACCESSOR(file);
 * becomes:
 *    APR_DECLARE(apr_pool_t *) apr_file_pool_get(const apr_file_t *thefile);
 * </pre>
 * @remark Doxygen unwraps this macro (via doxygen.conf) to provide 
 * actual help for each specific occurrence of apr_foo_pool_get.
 * @remark the linkage is specified for APR. It would be possible to expand
 *       the macros to support other linkages.
 */
#define APR_POOL_DECLARE_ACCESSOR(type) \
    APR_DECLARE(apr_pool_t *) apr_##type##_pool_get \
        (const apr_##type##_t *the##type)

/** 
 * Implementation helper macro to provide apr_foo_pool_get()s.
 *
 * In the implementation, the APR_POOL_IMPLEMENT_ACCESSOR() is used to
 * actually define the function. It assumes the field is named "pool".
 */
#define APR_POOL_IMPLEMENT_ACCESSOR(type) \
    APR_DECLARE(apr_pool_t *) apr_##type##_pool_get \
            (const apr_##type##_t *the##type) \
        { return the##type->pool; }

/**
 * Pool debug levels
 *
 * <pre>
 * | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
 * ---------------------------------
 * |   |   |   |   |   |   |   | x |  General debug code enabled (useful in
 *                                    combination with --with-efence).
 *
 * |   |   |   |   |   |   | x |   |  Verbose output on stderr (report
 *                                    CREATE, CLEAR, DESTROY).
 *
 * |   |   |   | x |   |   |   |   |  Verbose output on stderr (report
 *                                    PALLOC, PCALLOC).
 *
 * |   |   |   |   |   | x |   |   |  Lifetime checking. On each use of a
 *                                    pool, check its lifetime.  If the pool
 *                                    is out of scope, abort().
 *                                    In combination with the verbose flag
 *                                    above, it will output LIFE in such an
 *                                    event prior to aborting.
 *
 * |   |   |   |   | x |   |   |   |  Pool owner checking.  On each use of a
 *                                    pool, check if the current thread is the
 *                                    pool's owner.  If not, abort().  In
 *                                    combination with the verbose flag above,
 *                                    it will output OWNER in such an event
 *                                    prior to aborting.  Use the debug
 *                                    function apr_pool_owner_set() to switch
 *                                    a pool's ownership.
 *
 * When no debug level was specified, assume general debug mode.
 * If level 0 was specified, debugging is switched off.
 * </pre>
 */
#if defined(APR_POOL_DEBUG)
/* If APR_POOL_DEBUG is blank, we get 1; if it is a number, we get -1. */
#if (APR_POOL_DEBUG - APR_POOL_DEBUG -1 == 1)
#undef APR_POOL_DEBUG
#define APR_POOL_DEBUG 1
#endif
#else
#define APR_POOL_DEBUG 0
#endif

/** the place in the code where the particular function was called */
#define APR_POOL__FILE_LINE__ __FILE__ ":" APR_STRINGIFY(__LINE__)

/** A function that is called when allocation fails. */
typedef int (*apr_abortfunc_t)(int retcode);

/*
 * APR memory structure manipulators (pools, tables, and arrays).
 */

/*
 * Initialization
 */

/**
 * Setup all of the internal structures required to use pools
 * @remark Programs do NOT need to call this directly.  APR will call this
 *      automatically from apr_initialize.
 * @internal
 */
APR_DECLARE(apr_status_t) apr_pool_initialize(void);

/**
 * Tear down all of the internal structures required to use pools
 * @remark Programs do NOT need to call this directly.  APR will call this
 *      automatically from apr_terminate.
 * @internal
 */
APR_DECLARE(void) apr_pool_terminate(void);

/*
 * Pool creation/destruction
 */

#include "apr_allocator.h"

/**
 * Create a new pool.
 * @param newpool The pool we have just created.
 * @param parent The parent pool.  If this is NULL, the new pool is a root
 *        pool.  If it is non-NULL, the new pool will inherit all
 *        of its parent pool's attributes, except the apr_pool_t will
 *        be a sub-pool.
 * @param abort_fn A function to use if the pool cannot allocate more memory.
 * @param allocator The allocator to use with the new pool.  If NULL the
 *        allocator of the parent pool will be used.
 * @remark This function is thread-safe, in the sense that multiple threads
 *         can safely create subpools of the same parent pool concurrently.
 *         Similarly, a subpool can be created by one thread at the same
 *         time that another thread accesses the parent pool.
 */
APR_DECLARE(apr_status_t) apr_pool_create_ex(apr_pool_t **newpool,
                                             apr_pool_t *parent,
                                             apr_abortfunc_t abort_fn,
                                             apr_allocator_t *allocator)
                          __attribute__((nonnull(1)));

/**
 * Create a new pool.
 * @deprecated @see apr_pool_create_unmanaged_ex.
 */
APR_DECLARE(apr_status_t) apr_pool_create_core_ex(apr_pool_t **newpool,
                                                  apr_abortfunc_t abort_fn,
                                                  apr_allocator_t *allocator);

/**
 * Create a new unmanaged pool.
 * @param newpool The pool we have just created.
 * @param abort_fn A function to use if the pool cannot allocate more memory.
 * @param allocator The allocator to use with the new pool.  If NULL a
 *        new allocator will be created with the new pool as owner.
 * @remark An unmanaged pool is a special pool without a parent; it will
 *         NOT be destroyed upon apr_terminate.  It must be explicitly
 *         destroyed by calling apr_pool_destroy, to prevent memory leaks.
 *         Use of this function is discouraged, think twice about whether
 *         you really really need it.
 * @warning Any child cleanups registered against the new pool, or
 *         against sub-pools thereof, will not be executed during an
 *         invocation of apr_proc_create(), so resources created in an
 *         "unmanaged" pool hierarchy will leak to child processes.
 */
APR_DECLARE(apr_status_t) apr_pool_create_unmanaged_ex(apr_pool_t **newpool,
                                                   apr_abortfunc_t abort_fn,
                                                   apr_allocator_t *allocator)
                          __attribute__((nonnull(1)));

/**
 * Debug version of apr_pool_create_ex.
 * @param newpool @see apr_pool_create.
 * @param parent @see apr_pool_create.
 * @param abort_fn @see apr_pool_create.
 * @param allocator @see apr_pool_create.
 * @param file_line Where the function is called from.
 *        This is usually APR_POOL__FILE_LINE__.
 * @remark Only available when APR_POOL_DEBUG is defined.
 *         Call this directly if you have your apr_pool_create_ex
 *         calls in a wrapper function and wish to override
 *         the file_line argument to reflect the caller of
 *         your wrapper function.  If you do not have
 *         apr_pool_create_ex in a wrapper, trust the macro
 *         and don't call apr_pool_create_ex_debug directly.
 */
APR_DECLARE(apr_status_t) apr_pool_create_ex_debug(apr_pool_t **newpool,
                                                   apr_pool_t *parent,
                                                   apr_abortfunc_t abort_fn,
                                                   apr_allocator_t *allocator,
                                                   const char *file_line)
                          __attribute__((nonnull(1)));

#if APR_POOL_DEBUG
#define apr_pool_create_ex(newpool, parent, abort_fn, allocator)  \
    apr_pool_create_ex_debug(newpool, parent, abort_fn, allocator, \
                             APR_POOL__FILE_LINE__)
#endif

/**
 * Debug version of apr_pool_create_core_ex.
 * @deprecated @see apr_pool_create_unmanaged_ex_debug.
 */
APR_DECLARE(apr_status_t) apr_pool_create_core_ex_debug(apr_pool_t **newpool,
                                                   apr_abortfunc_t abort_fn,
                                                   apr_allocator_t *allocator,
                                                   const char *file_line);

/**
 * Debug version of apr_pool_create_unmanaged_ex.
 * @param newpool @see apr_pool_create_unmanaged.
 * @param abort_fn @see apr_pool_create_unmanaged.
 * @param allocator @see apr_pool_create_unmanaged.
 * @param file_line Where the function is called from.
 *        This is usually APR_POOL__FILE_LINE__.
 * @remark Only available when APR_POOL_DEBUG is defined.
 *         Call this directly if you have your apr_pool_create_unmanaged_ex
 *         calls in a wrapper function and wish to override
 *         the file_line argument to reflect the caller of
 *         your wrapper function.  If you do not have
 *         apr_pool_create_core_ex in a wrapper, trust the macro
 *         and don't call apr_pool_create_core_ex_debug directly.
 */
APR_DECLARE(apr_status_t) apr_pool_create_unmanaged_ex_debug(apr_pool_t **newpool,
                                                   apr_abortfunc_t abort_fn,
                                                   apr_allocator_t *allocator,
                                                   const char *file_line)
                          __attribute__((nonnull(1)));

#if APR_POOL_DEBUG
#define apr_pool_create_core_ex(newpool, abort_fn, allocator)  \
    apr_pool_create_unmanaged_ex_debug(newpool, abort_fn, allocator, \
                                  APR_POOL__FILE_LINE__)

#define apr_pool_create_unmanaged_ex(newpool, abort_fn, allocator)  \
    apr_pool_create_unmanaged_ex_debug(newpool, abort_fn, allocator, \
                                  APR_POOL__FILE_LINE__)

#endif

/**
 * Create a new pool.
 * @param newpool The pool we have just created.
 * @param parent The parent pool.  If this is NULL, the new pool is a root
 *        pool.  If it is non-NULL, the new pool will inherit all
 *        of its parent pool's attributes, except the apr_pool_t will
 *        be a sub-pool.
 * @remark This function is thread-safe, in the sense that multiple threads
 *         can safely create subpools of the same parent pool concurrently.
 *         Similarly, a subpool can be created by one thread at the same
 *         time that another thread accesses the parent pool.
 */
#if defined(DOXYGEN)
APR_DECLARE(apr_status_t) apr_pool_create(apr_pool_t **newpool,
                                          apr_pool_t *parent);
#else
#if APR_POOL_DEBUG
#define apr_pool_create(newpool, parent) \
    apr_pool_create_ex_debug(newpool, parent, NULL, NULL, \
                             APR_POOL__FILE_LINE__)
#else
#define apr_pool_create(newpool, parent) \
    apr_pool_create_ex(newpool, parent, NULL, NULL)
#endif
#endif

/**
 * Create a new unmanaged pool.
 * @param newpool The pool we have just created.
 */
#if defined(DOXYGEN)
APR_DECLARE(apr_status_t) apr_pool_create_core(apr_pool_t **newpool);
APR_DECLARE(apr_status_t) apr_pool_create_unmanaged(apr_pool_t **newpool);
#else
#if APR_POOL_DEBUG
#define apr_pool_create_core(newpool) \
    apr_pool_create_unmanaged_ex_debug(newpool, NULL, NULL, \
                                  APR_POOL__FILE_LINE__)
#define apr_pool_create_unmanaged(newpool) \
    apr_pool_create_unmanaged_ex_debug(newpool, NULL, NULL, \
                                  APR_POOL__FILE_LINE__)
#else
#define apr_pool_create_core(newpool) \
    apr_pool_create_unmanaged_ex(newpool, NULL, NULL)
#define apr_pool_create_unmanaged(newpool) \
    apr_pool_create_unmanaged_ex(newpool, NULL, NULL)
#endif
#endif

/**
 * Find the pool's allocator
 * @param pool The pool to get the allocator from.
 */
APR_DECLARE(apr_allocator_t *) apr_pool_allocator_get(apr_pool_t *pool)
                               __attribute__((nonnull(1)));

/**
 * Clear all memory in the pool and run all the cleanups. This also destroys all
 * subpools.
 * @param p The pool to clear
 * @remark This does not actually free the memory, it just allows the pool
 *         to re-use this memory for the next allocation.
 * @see apr_pool_destroy()
 */
APR_DECLARE(void) apr_pool_clear(apr_pool_t *p) __attribute__((nonnull(1)));

/**
 * Debug version of apr_pool_clear.
 * @param p See: apr_pool_clear.
 * @param file_line Where the function is called from.
 *        This is usually APR_POOL__FILE_LINE__.
 * @remark Only available when APR_POOL_DEBUG is defined.
 *         Call this directly if you have your apr_pool_clear
 *         calls in a wrapper function and wish to override
 *         the file_line argument to reflect the caller of
 *         your wrapper function.  If you do not have
 *         apr_pool_clear in a wrapper, trust the macro
 *         and don't call apr_pool_destroy_clear directly.
 */
APR_DECLARE(void) apr_pool_clear_debug(apr_pool_t *p,
                                       const char *file_line)
                  __attribute__((nonnull(1)));

#if APR_POOL_DEBUG
#define apr_pool_clear(p) \
    apr_pool_clear_debug(p, APR_POOL__FILE_LINE__)
#endif

/**
 * Destroy the pool. This takes similar action as apr_pool_clear() and then
 * frees all the memory.
 * @param p The pool to destroy
 * @remark This will actually free the memory
 */
APR_DECLARE(void) apr_pool_destroy(apr_pool_t *p) __attribute__((nonnull(1)));

/**
 * Debug version of apr_pool_destroy.
 * @param p See: apr_pool_destroy.
 * @param file_line Where the function is called from.
 *        This is usually APR_POOL__FILE_LINE__.
 * @remark Only available when APR_POOL_DEBUG is defined.
 *         Call this directly if you have your apr_pool_destroy
 *         calls in a wrapper function and wish to override
 *         the file_line argument to reflect the caller of
 *         your wrapper function.  If you do not have
 *         apr_pool_destroy in a wrapper, trust the macro
 *         and don't call apr_pool_destroy_debug directly.
 */
APR_DECLARE(void) apr_pool_destroy_debug(apr_pool_t *p,
                                         const char *file_line)
                  __attribute__((nonnull(1)));

#if APR_POOL_DEBUG
#define apr_pool_destroy(p) \
    apr_pool_destroy_debug(p, APR_POOL__FILE_LINE__)
#endif

/*
 * Memory allocation
 */

/**
 * Allocate a block of memory from a pool
 * @param p The pool to allocate from
 * @param size The amount of memory to allocate
 * @return The allocated memory
 */
APR_DECLARE(void *) apr_palloc(apr_pool_t *p, apr_size_t size)
#if defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4))
                    __attribute__((alloc_size(2)))
#endif
                    __attribute__((nonnull(1)));

/**
 * Debug version of apr_palloc
 * @param p See: apr_palloc
 * @param size See: apr_palloc
 * @param file_line Where the function is called from.
 *        This is usually APR_POOL__FILE_LINE__.
 * @return See: apr_palloc
 */
APR_DECLARE(void *) apr_palloc_debug(apr_pool_t *p, apr_size_t size,
                                     const char *file_line)
#if defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4))
                    __attribute__((alloc_size(2)))
#endif
                    __attribute__((nonnull(1)));

#if APR_POOL_DEBUG
#define apr_palloc(p, size) \
    apr_palloc_debug(p, size, APR_POOL__FILE_LINE__)
#endif

/**
 * Allocate a block of memory from a pool and set all of the memory to 0
 * @param p The pool to allocate from
 * @param size The amount of memory to allocate
 * @return The allocated memory
 */
#if defined(DOXYGEN)
APR_DECLARE(void *) apr_pcalloc(apr_pool_t *p, apr_size_t size);
#elif !APR_POOL_DEBUG
#define apr_pcalloc(p, size) memset(apr_palloc(p, size), 0, size)
#endif

/**
 * Debug version of apr_pcalloc
 * @param p See: apr_pcalloc
 * @param size See: apr_pcalloc
 * @param file_line Where the function is called from.
 *        This is usually APR_POOL__FILE_LINE__.
 * @return See: apr_pcalloc
 */
APR_DECLARE(void *) apr_pcalloc_debug(apr_pool_t *p, apr_size_t size,
                                      const char *file_line)
                    __attribute__((nonnull(1)));

#if APR_POOL_DEBUG
#define apr_pcalloc(p, size) \
    apr_pcalloc_debug(p, size, APR_POOL__FILE_LINE__)
#endif

/*
 * Pool Properties
 */

/**
 * Set the function to be called when an allocation failure occurs.
 * @remark If the program wants APR to exit on a memory allocation error,
 *      then this function can be called to set the callback to use (for
 *      performing cleanup and then exiting). If this function is not called,
 *      then APR will return an error and expect the calling program to
 *      deal with the error accordingly.
 */
APR_DECLARE(void) apr_pool_abort_set(apr_abortfunc_t abortfunc,
                                     apr_pool_t *pool)
                  __attribute__((nonnull(2)));

/**
 * Get the abort function associated with the specified pool.
 * @param pool The pool for retrieving the abort function.
 * @return The abort function for the given pool.
 */
APR_DECLARE(apr_abortfunc_t) apr_pool_abort_get(apr_pool_t *pool)
                             __attribute__((nonnull(1)));

/**
 * Get the parent pool of the specified pool.
 * @param pool The pool for retrieving the parent pool.
 * @return The parent of the given pool.
 */
APR_DECLARE(apr_pool_t *) apr_pool_parent_get(apr_pool_t *pool)
                          __attribute__((nonnull(1)));

/**
 * Determine if pool a is an ancestor of pool b.
 * @param a The pool to search
 * @param b The pool to search for
 * @return True if a is an ancestor of b, NULL is considered an ancestor
 *         of all pools.
 * @remark if compiled with APR_POOL_DEBUG, this function will also
 * return true if A is a pool which has been guaranteed by the caller
 * (using apr_pool_join) to have a lifetime at least as long as some
 * ancestor of pool B.
 */
APR_DECLARE(int) apr_pool_is_ancestor(apr_pool_t *a, apr_pool_t *b);

/**
 * Tag a pool (give it a name)
 * @param pool The pool to tag
 * @param tag  The tag
 */
APR_DECLARE(void) apr_pool_tag(apr_pool_t *pool, const char *tag)
                  __attribute__((nonnull(1)));

/*
 * User data management
 */

/**
 * Set the data associated with the current pool
 * @param data The user data associated with the pool.
 * @param key The key to use for association
 * @param cleanup The cleanup program to use to cleanup the data (NULL if none)
 * @param pool The current pool
 * @warning The data to be attached to the pool should have a life span
 *          at least as long as the pool it is being attached to.
 *
 *      Users of APR must take EXTREME care when choosing a key to
 *      use for their data.  It is possible to accidentally overwrite
 *      data by choosing a key that another part of the program is using.
 *      Therefore it is advised that steps are taken to ensure that unique
 *      keys are used for all of the userdata objects in a particular pool
 *      (the same key in two different pools or a pool and one of its
 *      subpools is okay) at all times.  Careful namespace prefixing of
 *      key names is a typical way to help ensure this uniqueness.
 *
 */
APR_DECLARE(apr_status_t) apr_pool_userdata_set(const void *data,
                                                const char *key,
                                                apr_status_t (*cleanup)(void *),
                                                apr_pool_t *pool)
                          __attribute__((nonnull(2,4)));

/**
 * Set the data associated with the current pool
 * @param data The user data associated with the pool.
 * @param key The key to use for association
 * @param cleanup The cleanup program to use to cleanup the data (NULL if none)
 * @param pool The current pool
 * @note same as apr_pool_userdata_set(), except that this version doesn't
 *       make a copy of the key (this function is useful, for example, when
 *       the key is a string literal)
 * @warning This should NOT be used if the key could change addresses by
 *       any means between the apr_pool_userdata_setn() call and a
 *       subsequent apr_pool_userdata_get() on that key, such as if a
 *       static string is used as a userdata key in a DSO and the DSO could
 *       be unloaded and reloaded between the _setn() and the _get().  You
 *       MUST use apr_pool_userdata_set() in such cases.
 * @warning More generally, the key and the data to be attached to the
 *       pool should have a life span at least as long as the pool itself.
 *
 */
APR_DECLARE(apr_status_t) apr_pool_userdata_setn(
                                const void *data, const char *key,
                                apr_status_t (*cleanup)(void *),
                                apr_pool_t *pool)
                          __attribute__((nonnull(2,4)));

/**
 * Return the data associated with the current pool.
 * @param data The user data associated with the pool.
 * @param key The key for the data to retrieve
 * @param pool The current pool.
 */
APR_DECLARE(apr_status_t) apr_pool_userdata_get(void **data, const char *key,
                                                apr_pool_t *pool)
                          __attribute__((nonnull(1,2,3)));

/**
 * @defgroup PoolCleanup  Pool Cleanup Functions
 *
 * Cleanups are performed in the reverse order they were registered.  That is:
 * Last In, First Out.  A cleanup function can safely allocate memory from
 * the pool that is being cleaned up. It can also safely register additional
 * cleanups which will be run LIFO, directly after the current cleanup
 * terminates.  Cleanups have to take caution in calling functions that
 * create subpools. Subpools, created during cleanup will NOT automatically
 * be cleaned up.  In other words, cleanups are to clean up after themselves.
 *
 * @{
 */

/**
 * Register a function to be called when a pool is cleared or destroyed
 * @param p The pool to register the cleanup with
 * @param data The data to pass to the cleanup function.
 * @param plain_cleanup The function to call when the pool is cleared
 *                      or destroyed
 * @param child_cleanup The function to call when a child process is about
 *                      to exec - this function is called in the child, obviously!
 */
APR_DECLARE(void) apr_pool_cleanup_register(
                            apr_pool_t *p, const void *data,
                            apr_status_t (*plain_cleanup)(void *),
                            apr_status_t (*child_cleanup)(void *))
                  __attribute__((nonnull(3,4)));

/**
 * Register a function to be called when a pool is cleared or destroyed.
 *
 * Unlike apr_pool_cleanup_register which registers a cleanup
 * that is called AFTER all subpools are destroyed, this function registers
 * a function that will be called before any of the subpools are destroyed.
 *
 * @param p The pool to register the cleanup with
 * @param data The data to pass to the cleanup function.
 * @param plain_cleanup The function to call when the pool is cleared
 *                      or destroyed
 */
APR_DECLARE(void) apr_pool_pre_cleanup_register(
                            apr_pool_t *p, const void *data,
                            apr_status_t (*plain_cleanup)(void *))
                  __attribute__((nonnull(3)));

/**
 * Remove a previously registered cleanup function.
 * 
 * The cleanup most recently registered with @a p having the same values of
 * @a data and @a cleanup will be removed.
 *
 * @param p The pool to remove the cleanup from
 * @param data The data of the registered cleanup
 * @param cleanup The function to remove from cleanup
 * @remarks For some strange reason only the plain_cleanup is handled by this
 *          function
 */
APR_DECLARE(void) apr_pool_cleanup_kill(apr_pool_t *p, const void *data,
                                        apr_status_t (*cleanup)(void *))
                  __attribute__((nonnull(3)));

/**
 * Replace the child cleanup function of a previously registered cleanup.
 * 
 * The cleanup most recently registered with @a p having the same values of
 * @a data and @a plain_cleanup will have the registered child cleanup
 * function replaced with @a child_cleanup.
 *
 * @param p The pool of the registered cleanup
 * @param data The data of the registered cleanup
 * @param plain_cleanup The plain cleanup function of the registered cleanup
 * @param child_cleanup The function to register as the child cleanup
 */
APR_DECLARE(void) apr_pool_child_cleanup_set(
                        apr_pool_t *p, const void *data,
                        apr_status_t (*plain_cleanup)(void *),
                        apr_status_t (*child_cleanup)(void *))
                  __attribute__((nonnull(3,4)));

/**
 * Run the specified cleanup function immediately and unregister it.
 *
 * The cleanup most recently registered with @a p having the same values of
 * @a data and @a cleanup will be removed and @a cleanup will be called
 * with @a data as the argument.
 *
 * @param p The pool to remove the cleanup from
 * @param data The data to remove from cleanup
 * @param cleanup The function to remove from cleanup
 */
APR_DECLARE(apr_status_t) apr_pool_cleanup_run(apr_pool_t *p, void *data,
                                               apr_status_t (*cleanup)(void *))
                          __attribute__((nonnull(3)));

/**
 * An empty cleanup function.
 * 
 * Passed to apr_pool_cleanup_register() when no cleanup is required.
 *
 * @param data The data to cleanup, will not be used by this function.
 */
APR_DECLARE_NONSTD(apr_status_t) apr_pool_cleanup_null(void *data);

/**
 * Run all registered child cleanups, in preparation for an exec()
 * call in a forked child -- close files, etc., but *don't* flush I/O
 * buffers, *don't* wait for subprocesses, and *don't* free any
 * memory.
 */
APR_DECLARE(void) apr_pool_cleanup_for_exec(void);

/** @} */

/**
 * @defgroup PoolDebug Pool Debugging functions
 *
 * pools have nested lifetimes -- sub_pools are destroyed when the
 * parent pool is cleared.  We allow certain liberties with operations
 * on things such as tables (and on other structures in a more general
 * sense) where we allow the caller to insert values into a table which
 * were not allocated from the table's pool.  The table's data will
 * remain valid as long as all the pools from which its values are
 * allocated remain valid.
 *
 * For example, if B is a sub pool of A, and you build a table T in
 * pool B, then it's safe to insert data allocated in A or B into T
 * (because B lives at most as long as A does, and T is destroyed when
 * B is cleared/destroyed).  On the other hand, if S is a table in
 * pool A, it is safe to insert data allocated in A into S, but it
 * is *not safe* to insert data allocated from B into S... because
 * B can be cleared/destroyed before A is (which would leave dangling
 * pointers in T's data structures).
 *
 * In general we say that it is safe to insert data into a table T
 * if the data is allocated in any ancestor of T's pool.  This is the
 * basis on which the APR_POOL_DEBUG code works -- it tests these ancestor
 * relationships for all data inserted into tables.  APR_POOL_DEBUG also
 * provides tools (apr_pool_find, and apr_pool_is_ancestor) for other
 * folks to implement similar restrictions for their own data
 * structures.
 *
 * However, sometimes this ancestor requirement is inconvenient --
 * sometimes it's necessary to create a sub pool where the sub pool is
 * guaranteed to have the same lifetime as the parent pool.  This is a
 * guarantee implemented by the *caller*, not by the pool code.  That
 * is, the caller guarantees they won't destroy the sub pool
 * individually prior to destroying the parent pool.
 *
 * In this case the caller must call apr_pool_join() to indicate this
 * guarantee to the APR_POOL_DEBUG code.
 *
 * These functions are only implemented when #APR_POOL_DEBUG is set.
 *
 * @{
 */
#if APR_POOL_DEBUG || defined(DOXYGEN)
/**
 * Guarantee that a subpool has the same lifetime as the parent.
 * @param p The parent pool
 * @param sub The subpool
 */
APR_DECLARE(void) apr_pool_join(apr_pool_t *p, apr_pool_t *sub)
                  __attribute__((nonnull(2)));

/**
 * Find a pool from something allocated in it.
 * @param mem The thing allocated in the pool
 * @return The pool it is allocated in
 */
APR_DECLARE(apr_pool_t *) apr_pool_find(const void *mem);

/**
 * Report the number of bytes currently in the pool
 * @param p The pool to inspect
 * @param recurse Recurse/include the subpools' sizes
 * @return The number of bytes
 */
APR_DECLARE(apr_size_t) apr_pool_num_bytes(apr_pool_t *p, int recurse)
                        __attribute__((nonnull(1)));

/**
 * Lock a pool
 * @param pool The pool to lock
 * @param flag  The flag
 */
APR_DECLARE(void) apr_pool_lock(apr_pool_t *pool, int flag);

/** @} */

#else /* APR_POOL_DEBUG or DOXYGEN */

#ifdef apr_pool_join
#undef apr_pool_join
#endif
#define apr_pool_join(a,b)

#ifdef apr_pool_lock
#undef apr_pool_lock
#endif
#define apr_pool_lock(pool, lock)

#endif /* APR_POOL_DEBUG or DOXYGEN */

/** @} */

#ifdef __cplusplus
}
#endif

#endif /* !APR_POOLS_H */

Back