Coverage Report

Created: 2023-03-26 06:28

/src/httpd/srclib/apr/include/apr_pools.h
Line
Count
Source (jump to first uncovered line)
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
0
        { return the##type->pool; }
Unexecuted instantiation: apr_hash_pool_get
Unexecuted instantiation: apr_file_pool_get
Unexecuted instantiation: apr_global_mutex_pool_get
Unexecuted instantiation: apr_proc_mutex_pool_get
Unexecuted instantiation: apr_thread_mutex_pool_get
Unexecuted instantiation: apr_socket_pool_get
Unexecuted instantiation: apr_shm_pool_get
Unexecuted instantiation: apr_thread_pool_get
Unexecuted instantiation: apr_thread_cond_pool_get
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
1.43M
#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
 */
164
APR_DECLARE(apr_status_t) apr_pool_initialize(void);
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
 * 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
 */
195
APR_DECLARE(apr_status_t) apr_pool_create_ex(apr_pool_t **newpool,
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
 */
217
APR_DECLARE(apr_status_t) apr_pool_create_unmanaged_ex(apr_pool_t **newpool,
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
 */
238
APR_DECLARE(apr_status_t) apr_pool_create_ex_debug(apr_pool_t **newpool,
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
5.33k
    apr_pool_create_ex_debug(newpool, parent, abort_fn, allocator, \
248
5.33k
                             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
 */
266
APR_DECLARE(apr_status_t) apr_pool_create_unmanaged_ex_debug(apr_pool_t **newpool,
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
0
    apr_pool_create_unmanaged_ex_debug(newpool, abort_fn, allocator, \
275
0
                                  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)
292
APR_DECLARE(apr_status_t) apr_pool_create(apr_pool_t **newpool,
293
                                          apr_pool_t *parent);
294
#else
295
#if APR_POOL_DEBUG
296
#define apr_pool_create(newpool, parent) \
297
531
    apr_pool_create_ex_debug(newpool, parent, NULL, NULL, \
298
531
                             APR_POOL__FILE_LINE__)
299
#else
300
#define apr_pool_create(newpool, parent) \
301
6.03k
    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)
310
APR_DECLARE(apr_status_t) apr_pool_create_unmanaged(apr_pool_t **newpool);
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
 */
326
APR_DECLARE(apr_allocator_t *) apr_pool_allocator_get(apr_pool_t *pool)
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
 */
352
APR_DECLARE(void) apr_pool_clear_debug(apr_pool_t *p,
353
                                       const char *file_line)
354
                  __attribute__((nonnull(1)));
355
356
#if APR_POOL_DEBUG
357
#define apr_pool_clear(p) \
358
0
    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
 */
382
APR_DECLARE(void) apr_pool_destroy_debug(apr_pool_t *p,
383
                                         const char *file_line)
384
                  __attribute__((nonnull(1)));
385
386
#if APR_POOL_DEBUG
387
#define apr_pool_destroy(p) \
388
5.33k
    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
1.41M
    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
10.9k
    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
 */
470
APR_DECLARE(void) apr_pool_abort_set(apr_abortfunc_t abortfunc,
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
 */
479
APR_DECLARE(apr_abortfunc_t) apr_pool_abort_get(apr_pool_t *pool)
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
 */
487
APR_DECLARE(apr_pool_t *) apr_pool_parent_get(apr_pool_t *pool)
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
 */
501
APR_DECLARE(int) apr_pool_is_ancestor(apr_pool_t *a, apr_pool_t *b);
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
 */
516
APR_DECLARE(const char *) apr_pool_get_tag(apr_pool_t *pool)
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
 */
542
APR_DECLARE(apr_status_t) apr_pool_userdata_set(const void *data,
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
 */
567
APR_DECLARE(apr_status_t) apr_pool_userdata_setn(
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
 */
607
APR_DECLARE(void) apr_pool_cleanup_register(
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
 */
625
APR_DECLARE(void) apr_pool_pre_cleanup_register(
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
 */
658
APR_DECLARE(void) apr_pool_child_cleanup_set(
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
 */
675
APR_DECLARE(apr_status_t) apr_pool_cleanup_run(apr_pool_t *p, void *data,
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
 */
686
APR_DECLARE_NONSTD(apr_status_t) apr_pool_cleanup_null(void *data);
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
 */
694
APR_DECLARE(void) apr_pool_cleanup_for_exec(void);
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
 */
758
APR_DECLARE(void) apr_pool_join(apr_pool_t *p, apr_pool_t *sub)
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
 */
766
APR_DECLARE(apr_pool_t *) apr_pool_find(const void *mem);
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 */