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