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