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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
22 * @brief APR memory allocation
24 * Resource allocation routines...
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()).
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.
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.
44 #include "apr_errno.h"
45 #include "apr_general.h" /* for APR_STRINGIFY */
46 #define APR_WANT_MEMFUNC /**< for no good reason? */
54 * @defgroup apr_pools Memory Pool Functions
59 /** The fundamental pool type */
60 typedef struct apr_pool_t apr_pool_t;
64 * Declaration helper macro to construct apr_foo_pool_get()s.
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.
69 * APR_POOL_DECLARE_ACCESSOR() is used in a header file to declare the
70 * accessor function. A typical usage and result would be:
72 * APR_POOL_DECLARE_ACCESSOR(file);
74 * APR_DECLARE(apr_pool_t *) apr_file_pool_get(apr_file_t *ob);
76 * @remark Doxygen unwraps this macro (via doxygen.conf) to provide
77 * actual help for each specific occurance of apr_foo_pool_get.
78 * @remark the linkage is specified for APR. It would be possible to expand
79 * the macros to support other linkages.
81 #define APR_POOL_DECLARE_ACCESSOR(type) \
82 APR_DECLARE(apr_pool_t *) apr_##type##_pool_get \
83 (const apr_##type##_t *the##type)
86 * Implementation helper macro to provide apr_foo_pool_get()s.
88 * In the implementation, the APR_POOL_IMPLEMENT_ACCESSOR() is used to
89 * actually define the function. It assumes the field is named "pool".
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; }
101 * | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
102 * ---------------------------------
103 * | | | | | | | | x | General debug code enabled (useful in
104 * combination with --with-efence).
106 * | | | | | | | x | | Verbose output on stderr (report
107 * CREATE, CLEAR, DESTROY).
109 * | | | | x | | | | | Verbose output on stderr (report
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.
119 * | | | | | x | | | | Pool owner checking. On each use of a
120 * pool, check if the current thread is the
121 * pools owner. If not, abort(). In
122 * combination with the verbose flag above,
123 * it will output OWNER in such an event
124 * prior to aborting. Use the debug
125 * function apr_pool_owner_set() to switch
128 * When no debug level was specified, assume general debug mode.
129 * If level 0 was specified, debugging is switched off
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
139 #define APR_POOL_DEBUG 0
142 /** the place in the code where the particular function was called */
143 #define APR_POOL__FILE_LINE__ __FILE__ ":" APR_STRINGIFY(__LINE__)
147 /** A function that is called when allocation fails. */
148 typedef int (*apr_abortfunc_t)(int retcode);
151 * APR memory structure manipulators (pools, tables, and arrays).
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.
164 APR_DECLARE(apr_status_t) apr_pool_initialize(void);
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.
172 APR_DECLARE(void) apr_pool_terminate(void);
176 * Pool creation/destruction
179 #include "apr_allocator.h"
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
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.
196 APR_DECLARE(apr_status_t) apr_pool_create_ex(apr_pool_t **newpool,
198 apr_abortfunc_t abort_fn,
199 apr_allocator_t *allocator)
200 __attribute__((nonnull(1)));
204 * @deprecated @see apr_pool_create_unmanaged_ex.
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);
211 * Create a new unmanaged pool.
212 * @param newpool The pool we have just created.
213 * @param abort_fn A function to use if the pool cannot allocate more memory.
214 * @param allocator The allocator to use with the new pool. If NULL a
215 * new allocator will be crated with newpool as owner.
216 * @remark An unmanaged pool is a special pool without a parent; it will
217 * NOT be destroyed upon apr_terminate. It must be explicitly
218 * destroyed by calling apr_pool_destroy, to prevent memory leaks.
219 * Use of this function is discouraged, think twice about whether
220 * you really really need it.
222 APR_DECLARE(apr_status_t) apr_pool_create_unmanaged_ex(apr_pool_t **newpool,
223 apr_abortfunc_t abort_fn,
224 apr_allocator_t *allocator)
225 __attribute__((nonnull(1)));
228 * Debug version of apr_pool_create_ex.
229 * @param newpool @see apr_pool_create.
230 * @param parent @see apr_pool_create.
231 * @param abort_fn @see apr_pool_create.
232 * @param allocator @see apr_pool_create.
233 * @param file_line Where the function is called from.
234 * This is usually APR_POOL__FILE_LINE__.
235 * @remark Only available when APR_POOL_DEBUG is defined.
236 * Call this directly if you have you apr_pool_create_ex
237 * calls in a wrapper function and wish to override
238 * the file_line argument to reflect the caller of
239 * your wrapper function. If you do not have
240 * apr_pool_create_ex in a wrapper, trust the macro
241 * and don't call apr_pool_create_ex_debug directly.
243 APR_DECLARE(apr_status_t) apr_pool_create_ex_debug(apr_pool_t **newpool,
245 apr_abortfunc_t abort_fn,
246 apr_allocator_t *allocator,
247 const char *file_line)
248 __attribute__((nonnull(1)));
251 #define apr_pool_create_ex(newpool, parent, abort_fn, allocator) \
252 apr_pool_create_ex_debug(newpool, parent, abort_fn, allocator, \
253 APR_POOL__FILE_LINE__)
257 * Debug version of apr_pool_create_core_ex.
258 * @deprecated @see apr_pool_create_unmanaged_ex_debug.
260 APR_DECLARE(apr_status_t) apr_pool_create_core_ex_debug(apr_pool_t **newpool,
261 apr_abortfunc_t abort_fn,
262 apr_allocator_t *allocator,
263 const char *file_line);
266 * Debug version of apr_pool_create_unmanaged_ex.
267 * @param newpool @see apr_pool_create_unmanaged.
268 * @param abort_fn @see apr_pool_create_unmanaged.
269 * @param allocator @see apr_pool_create_unmanaged.
270 * @param file_line Where the function is called from.
271 * This is usually APR_POOL__FILE_LINE__.
272 * @remark Only available when APR_POOL_DEBUG is defined.
273 * Call this directly if you have you apr_pool_create_unmanaged_ex
274 * calls in a wrapper function and wish to override
275 * the file_line argument to reflect the caller of
276 * your wrapper function. If you do not have
277 * apr_pool_create_core_ex in a wrapper, trust the macro
278 * and don't call apr_pool_create_core_ex_debug directly.
280 APR_DECLARE(apr_status_t) apr_pool_create_unmanaged_ex_debug(apr_pool_t **newpool,
281 apr_abortfunc_t abort_fn,
282 apr_allocator_t *allocator,
283 const char *file_line)
284 __attribute__((nonnull(1)));
287 #define apr_pool_create_core_ex(newpool, abort_fn, allocator) \
288 apr_pool_create_unmanaged_ex_debug(newpool, abort_fn, allocator, \
289 APR_POOL__FILE_LINE__)
291 #define apr_pool_create_unmanaged_ex(newpool, abort_fn, allocator) \
292 apr_pool_create_unmanaged_ex_debug(newpool, abort_fn, allocator, \
293 APR_POOL__FILE_LINE__)
299 * @param newpool The pool we have just created.
300 * @param parent The parent pool. If this is NULL, the new pool is a root
301 * pool. If it is non-NULL, the new pool will inherit all
302 * of its parent pool's attributes, except the apr_pool_t will
304 * @remark This function is thread-safe, in the sense that multiple threads
305 * can safely create subpools of the same parent pool concurrently.
306 * Similarly, a subpool can be created by one thread at the same
307 * time that another thread accesses the parent pool.
310 APR_DECLARE(apr_status_t) apr_pool_create(apr_pool_t **newpool,
314 #define apr_pool_create(newpool, parent) \
315 apr_pool_create_ex_debug(newpool, parent, NULL, NULL, \
316 APR_POOL__FILE_LINE__)
318 #define apr_pool_create(newpool, parent) \
319 apr_pool_create_ex(newpool, parent, NULL, NULL)
325 * @param newpool The pool we have just created.
328 APR_DECLARE(apr_status_t) apr_pool_create_core(apr_pool_t **newpool);
329 APR_DECLARE(apr_status_t) apr_pool_create_unmanaged(apr_pool_t **newpool);
332 #define apr_pool_create_core(newpool) \
333 apr_pool_create_unmanaged_ex_debug(newpool, NULL, NULL, \
334 APR_POOL__FILE_LINE__)
335 #define apr_pool_create_unmanaged(newpool) \
336 apr_pool_create_unmanaged_ex_debug(newpool, NULL, NULL, \
337 APR_POOL__FILE_LINE__)
339 #define apr_pool_create_core(newpool) \
340 apr_pool_create_unmanaged_ex(newpool, NULL, NULL)
341 #define apr_pool_create_unmanaged(newpool) \
342 apr_pool_create_unmanaged_ex(newpool, NULL, NULL)
347 * Find the pool's allocator
348 * @param pool The pool to get the allocator from.
350 APR_DECLARE(apr_allocator_t *) apr_pool_allocator_get(apr_pool_t *pool)
351 __attribute__((nonnull(1)));
354 * Clear all memory in the pool and run all the cleanups. This also destroys all
356 * @param p The pool to clear
357 * @remark This does not actually free the memory, it just allows the pool
358 * to re-use this memory for the next allocation.
359 * @see apr_pool_destroy()
361 APR_DECLARE(void) apr_pool_clear(apr_pool_t *p) __attribute__((nonnull(1)));
364 * Debug version of apr_pool_clear.
365 * @param p See: apr_pool_clear.
366 * @param file_line Where the function is called from.
367 * This is usually APR_POOL__FILE_LINE__.
368 * @remark Only available when APR_POOL_DEBUG is defined.
369 * Call this directly if you have you apr_pool_clear
370 * calls in a wrapper function and wish to override
371 * the file_line argument to reflect the caller of
372 * your wrapper function. If you do not have
373 * apr_pool_clear in a wrapper, trust the macro
374 * and don't call apr_pool_destroy_clear directly.
376 APR_DECLARE(void) apr_pool_clear_debug(apr_pool_t *p,
377 const char *file_line)
378 __attribute__((nonnull(1)));
381 #define apr_pool_clear(p) \
382 apr_pool_clear_debug(p, APR_POOL__FILE_LINE__)
386 * Destroy the pool. This takes similar action as apr_pool_clear() and then
387 * frees all the memory.
388 * @param p The pool to destroy
389 * @remark This will actually free the memory
391 APR_DECLARE(void) apr_pool_destroy(apr_pool_t *p) __attribute__((nonnull(1)));
394 * Debug version of apr_pool_destroy.
395 * @param p See: apr_pool_destroy.
396 * @param file_line Where the function is called from.
397 * This is usually APR_POOL__FILE_LINE__.
398 * @remark Only available when APR_POOL_DEBUG is defined.
399 * Call this directly if you have you apr_pool_destroy
400 * calls in a wrapper function and wish to override
401 * the file_line argument to reflect the caller of
402 * your wrapper function. If you do not have
403 * apr_pool_destroy in a wrapper, trust the macro
404 * and don't call apr_pool_destroy_debug directly.
406 APR_DECLARE(void) apr_pool_destroy_debug(apr_pool_t *p,
407 const char *file_line)
408 __attribute__((nonnull(1)));
411 #define apr_pool_destroy(p) \
412 apr_pool_destroy_debug(p, APR_POOL__FILE_LINE__)
421 * Allocate a block of memory from a pool
422 * @param p The pool to allocate from
423 * @param size The amount of memory to allocate
424 * @return The allocated memory
426 APR_DECLARE(void *) apr_palloc(apr_pool_t *p, apr_size_t size)
427 #if defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4))
428 __attribute__((alloc_size(2)))
430 __attribute__((nonnull(1)));
433 * Debug version of apr_palloc
434 * @param p See: apr_palloc
435 * @param size See: apr_palloc
436 * @param file_line Where the function is called from.
437 * This is usually APR_POOL__FILE_LINE__.
438 * @return See: apr_palloc
440 APR_DECLARE(void *) apr_palloc_debug(apr_pool_t *p, apr_size_t size,
441 const char *file_line)
442 #if defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4))
443 __attribute__((alloc_size(2)))
445 __attribute__((nonnull(1)));
448 #define apr_palloc(p, size) \
449 apr_palloc_debug(p, size, APR_POOL__FILE_LINE__)
453 * Allocate a block of memory from a pool and set all of the memory to 0
454 * @param p The pool to allocate from
455 * @param size The amount of memory to allocate
456 * @return The allocated memory
459 APR_DECLARE(void *) apr_pcalloc(apr_pool_t *p, apr_size_t size);
460 #elif !APR_POOL_DEBUG
461 #define apr_pcalloc(p, size) memset(apr_palloc(p, size), 0, size)
465 * Debug version of apr_pcalloc
466 * @param p See: apr_pcalloc
467 * @param size See: apr_pcalloc
468 * @param file_line Where the function is called from.
469 * This is usually APR_POOL__FILE_LINE__.
470 * @return See: apr_pcalloc
472 APR_DECLARE(void *) apr_pcalloc_debug(apr_pool_t *p, apr_size_t size,
473 const char *file_line)
474 __attribute__((nonnull(1)));
477 #define apr_pcalloc(p, size) \
478 apr_pcalloc_debug(p, size, APR_POOL__FILE_LINE__)
487 * Set the function to be called when an allocation failure occurs.
488 * @remark If the program wants APR to exit on a memory allocation error,
489 * then this function can be called to set the callback to use (for
490 * performing cleanup and then exiting). If this function is not called,
491 * then APR will return an error and expect the calling program to
492 * deal with the error accordingly.
494 APR_DECLARE(void) apr_pool_abort_set(apr_abortfunc_t abortfunc,
496 __attribute__((nonnull(2)));
499 * Get the abort function associated with the specified pool.
500 * @param pool The pool for retrieving the abort function.
501 * @return The abort function for the given pool.
503 APR_DECLARE(apr_abortfunc_t) apr_pool_abort_get(apr_pool_t *pool)
504 __attribute__((nonnull(1)));
507 * Get the parent pool of the specified pool.
508 * @param pool The pool for retrieving the parent pool.
509 * @return The parent of the given pool.
511 APR_DECLARE(apr_pool_t *) apr_pool_parent_get(apr_pool_t *pool)
512 __attribute__((nonnull(1)));
515 * Determine if pool a is an ancestor of pool b.
516 * @param a The pool to search
517 * @param b The pool to search for
518 * @return True if a is an ancestor of b, NULL is considered an ancestor
520 * @remark if compiled with APR_POOL_DEBUG, this function will also
521 * return true if A is a pool which has been guaranteed by the caller
522 * (using apr_pool_join) to have a lifetime at least as long as some
523 * ancestor of pool B.
525 APR_DECLARE(int) apr_pool_is_ancestor(apr_pool_t *a, apr_pool_t *b);
528 * Tag a pool (give it a name)
529 * @param pool The pool to tag
532 APR_DECLARE(void) apr_pool_tag(apr_pool_t *pool, const char *tag)
533 __attribute__((nonnull(1)));
537 * User data management
541 * Set the data associated with the current pool
542 * @param data The user data associated with the pool.
543 * @param key The key to use for association
544 * @param cleanup The cleanup program to use to cleanup the data (NULL if none)
545 * @param pool The current pool
546 * @warning The data to be attached to the pool should have a life span
547 * at least as long as the pool it is being attached to.
549 * Users of APR must take EXTREME care when choosing a key to
550 * use for their data. It is possible to accidentally overwrite
551 * data by choosing a key that another part of the program is using.
552 * Therefore it is advised that steps are taken to ensure that unique
553 * keys are used for all of the userdata objects in a particular pool
554 * (the same key in two different pools or a pool and one of its
555 * subpools is okay) at all times. Careful namespace prefixing of
556 * key names is a typical way to help ensure this uniqueness.
559 APR_DECLARE(apr_status_t) apr_pool_userdata_set(const void *data,
561 apr_status_t (*cleanup)(void *),
563 __attribute__((nonnull(2,4)));
566 * Set the data associated with the current pool
567 * @param data The user data associated with the pool.
568 * @param key The key to use for association
569 * @param cleanup The cleanup program to use to cleanup the data (NULL if none)
570 * @param pool The current pool
571 * @note same as apr_pool_userdata_set(), except that this version doesn't
572 * make a copy of the key (this function is useful, for example, when
573 * the key is a string literal)
574 * @warning This should NOT be used if the key could change addresses by
575 * any means between the apr_pool_userdata_setn() call and a
576 * subsequent apr_pool_userdata_get() on that key, such as if a
577 * static string is used as a userdata key in a DSO and the DSO could
578 * be unloaded and reloaded between the _setn() and the _get(). You
579 * MUST use apr_pool_userdata_set() in such cases.
580 * @warning More generally, the key and the data to be attached to the
581 * pool should have a life span at least as long as the pool itself.
584 APR_DECLARE(apr_status_t) apr_pool_userdata_setn(
585 const void *data, const char *key,
586 apr_status_t (*cleanup)(void *),
588 __attribute__((nonnull(2,4)));
591 * Return the data associated with the current pool.
592 * @param data The user data associated with the pool.
593 * @param key The key for the data to retrieve
594 * @param pool The current pool.
596 APR_DECLARE(apr_status_t) apr_pool_userdata_get(void **data, const char *key,
598 __attribute__((nonnull(1,2,3)));
602 * @defgroup PoolCleanup Pool Cleanup Functions
604 * Cleanups are performed in the reverse order they were registered. That is:
605 * Last In, First Out. A cleanup function can safely allocate memory from
606 * the pool that is being cleaned up. It can also safely register additional
607 * cleanups which will be run LIFO, directly after the current cleanup
608 * terminates. Cleanups have to take caution in calling functions that
609 * create subpools. Subpools, created during cleanup will NOT automatically
610 * be cleaned up. In other words, cleanups are to clean up after themselves.
616 * Register a function to be called when a pool is cleared or destroyed
617 * @param p The pool register the cleanup with
618 * @param data The data to pass to the cleanup function.
619 * @param plain_cleanup The function to call when the pool is cleared
621 * @param child_cleanup The function to call when a child process is about
622 * to exec - this function is called in the child, obviously!
624 APR_DECLARE(void) apr_pool_cleanup_register(
625 apr_pool_t *p, const void *data,
626 apr_status_t (*plain_cleanup)(void *),
627 apr_status_t (*child_cleanup)(void *))
628 __attribute__((nonnull(3,4)));
631 * Register a function to be called when a pool is cleared or destroyed.
633 * Unlike apr_pool_cleanup_register which register a cleanup
634 * that is called AFTER all subpools are destroyed this function register
635 * a function that will be called before any of the subpool is destoryed.
637 * @param p The pool register the cleanup with
638 * @param data The data to pass to the cleanup function.
639 * @param plain_cleanup The function to call when the pool is cleared
642 APR_DECLARE(void) apr_pool_pre_cleanup_register(
643 apr_pool_t *p, const void *data,
644 apr_status_t (*plain_cleanup)(void *))
645 __attribute__((nonnull(3)));
648 * Remove a previously registered cleanup function.
650 * The cleanup most recently registered with @a p having the same values of
651 * @a data and @a cleanup will be removed.
653 * @param p The pool to remove the cleanup from
654 * @param data The data of the registered cleanup
655 * @param cleanup The function to remove from cleanup
656 * @remarks For some strange reason only the plain_cleanup is handled by this
659 APR_DECLARE(void) apr_pool_cleanup_kill(apr_pool_t *p, const void *data,
660 apr_status_t (*cleanup)(void *))
661 __attribute__((nonnull(3)));
664 * Replace the child cleanup function of a previously registered cleanup.
666 * The cleanup most recently registered with @a p having the same values of
667 * @a data and @a plain_cleanup will have the registered child cleanup
668 * function replaced with @a child_cleanup.
670 * @param p The pool of the registered cleanup
671 * @param data The data of the registered cleanup
672 * @param plain_cleanup The plain cleanup function of the registered cleanup
673 * @param child_cleanup The function to register as the child cleanup
675 APR_DECLARE(void) apr_pool_child_cleanup_set(
676 apr_pool_t *p, const void *data,
677 apr_status_t (*plain_cleanup)(void *),
678 apr_status_t (*child_cleanup)(void *))
679 __attribute__((nonnull(3,4)));
682 * Run the specified cleanup function immediately and unregister it.
684 * The cleanup most recently registered with @a p having the same values of
685 * @a data and @a cleanup will be removed and @a cleanup will be called
686 * with @a data as the argument.
688 * @param p The pool to remove the cleanup from
689 * @param data The data to remove from cleanup
690 * @param cleanup The function to remove from cleanup
692 APR_DECLARE(apr_status_t) apr_pool_cleanup_run(apr_pool_t *p, void *data,
693 apr_status_t (*cleanup)(void *))
694 __attribute__((nonnull(3)));
697 * An empty cleanup function.
699 * Passed to apr_pool_cleanup_register() when no cleanup is required.
701 * @param data The data to cleanup, will not be used by this function.
703 APR_DECLARE_NONSTD(apr_status_t) apr_pool_cleanup_null(void *data);
706 * Run all registered child cleanups, in preparation for an exec()
707 * call in a forked child -- close files, etc., but *don't* flush I/O
708 * buffers, *don't* wait for subprocesses, and *don't* free any
711 APR_DECLARE(void) apr_pool_cleanup_for_exec(void);
716 * @defgroup PoolDebug Pool Debugging functions.
718 * pools have nested lifetimes -- sub_pools are destroyed when the
719 * parent pool is cleared. We allow certain liberties with operations
720 * on things such as tables (and on other structures in a more general
721 * sense) where we allow the caller to insert values into a table which
722 * were not allocated from the table's pool. The table's data will
723 * remain valid as long as all the pools from which its values are
724 * allocated remain valid.
726 * For example, if B is a sub pool of A, and you build a table T in
727 * pool B, then it's safe to insert data allocated in A or B into T
728 * (because B lives at most as long as A does, and T is destroyed when
729 * B is cleared/destroyed). On the other hand, if S is a table in
730 * pool A, it is safe to insert data allocated in A into S, but it
731 * is *not safe* to insert data allocated from B into S... because
732 * B can be cleared/destroyed before A is (which would leave dangling
733 * pointers in T's data structures).
735 * In general we say that it is safe to insert data into a table T
736 * if the data is allocated in any ancestor of T's pool. This is the
737 * basis on which the APR_POOL_DEBUG code works -- it tests these ancestor
738 * relationships for all data inserted into tables. APR_POOL_DEBUG also
739 * provides tools (apr_pool_find, and apr_pool_is_ancestor) for other
740 * folks to implement similar restrictions for their own data
743 * However, sometimes this ancestor requirement is inconvenient --
744 * sometimes it's necessary to create a sub pool where the sub pool is
745 * guaranteed to have the same lifetime as the parent pool. This is a
746 * guarantee implemented by the *caller*, not by the pool code. That
747 * is, the caller guarantees they won't destroy the sub pool
748 * individually prior to destroying the parent pool.
750 * In this case the caller must call apr_pool_join() to indicate this
751 * guarantee to the APR_POOL_DEBUG code.
753 * These functions are only implemented when #APR_POOL_DEBUG is set.
757 #if APR_POOL_DEBUG || defined(DOXYGEN)
759 * Guarantee that a subpool has the same lifetime as the parent.
760 * @param p The parent pool
761 * @param sub The subpool
763 APR_DECLARE(void) apr_pool_join(apr_pool_t *p, apr_pool_t *sub)
764 __attribute__((nonnull(2)));
767 * Find a pool from something allocated in it.
768 * @param mem The thing allocated in the pool
769 * @return The pool it is allocated in
771 APR_DECLARE(apr_pool_t *) apr_pool_find(const void *mem);
774 * Report the number of bytes currently in the pool
775 * @param p The pool to inspect
776 * @param recurse Recurse/include the subpools' sizes
777 * @return The number of bytes
779 APR_DECLARE(apr_size_t) apr_pool_num_bytes(apr_pool_t *p, int recurse)
780 __attribute__((nonnull(1)));
784 * @param pool The pool to lock
785 * @param flag The flag
787 APR_DECLARE(void) apr_pool_lock(apr_pool_t *pool, int flag);
791 #else /* APR_POOL_DEBUG or DOXYGEN */
796 #define apr_pool_join(a,b)
801 #define apr_pool_lock(pool, lock)
803 #endif /* APR_POOL_DEBUG or DOXYGEN */
811 #endif /* !APR_POOLS_H */