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