/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 */ |