apr_pools.h

Go to the documentation of this file.
00001 /* Licensed to the Apache Software Foundation (ASF) under one or more
00002  * contributor license agreements.  See the NOTICE file distributed with
00003  * this work for additional information regarding copyright ownership.
00004  * The ASF licenses this file to You under the Apache License, Version 2.0
00005  * (the "License"); you may not use this file except in compliance with
00006  * the License.  You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef APR_POOLS_H
00018 #define APR_POOLS_H
00019 
00037 #include "apr.h"
00038 #include "apr_errno.h"
00039 #include "apr_general.h" /* for APR_STRINGIFY */
00040 #define APR_WANT_MEMFUNC 
00041 #include "apr_want.h"
00042 
00043 #ifdef __cplusplus
00044 extern "C" {
00045 #endif
00046 
00054 typedef struct apr_pool_t apr_pool_t;
00055 
00056 
00075 #define APR_POOL_DECLARE_ACCESSOR(type) \
00076     APR_DECLARE(apr_pool_t *) apr_##type##_pool_get \
00077         (const apr_##type##_t *the##type)
00078 
00085 #define APR_POOL_IMPLEMENT_ACCESSOR(type) \
00086     APR_DECLARE(apr_pool_t *) apr_##type##_pool_get \
00087             (const apr_##type##_t *the##type) \
00088         { return the##type->pool; }
00089 
00090 
00126 #if defined(APR_POOL_DEBUG)
00127 #if (APR_POOL_DEBUG != 0) && (APR_POOL_DEBUG - 0 == 0)
00128 #undef APR_POOL_DEBUG
00129 #define APR_POOL_DEBUG 1
00130 #endif
00131 #else
00132 #define APR_POOL_DEBUG 0
00133 #endif
00134 
00136 #define APR_POOL__FILE_LINE__ __FILE__ ":" APR_STRINGIFY(__LINE__)
00137 
00138 
00139 
00141 typedef int (*apr_abortfunc_t)(int retcode);
00142 
00143 /*
00144  * APR memory structure manipulators (pools, tables, and arrays).
00145  */
00146 
00147 /*
00148  * Initialization
00149  */
00150 
00157 APR_DECLARE(apr_status_t) apr_pool_initialize(void);
00158 
00165 APR_DECLARE(void) apr_pool_terminate(void);
00166 
00167 
00168 /*
00169  * Pool creation/destruction
00170  */
00171 
00172 #include "apr_allocator.h"
00173 
00185 APR_DECLARE(apr_status_t) apr_pool_create_ex(apr_pool_t **newpool,
00186                                              apr_pool_t *parent,
00187                                              apr_abortfunc_t abort_fn,
00188                                              apr_allocator_t *allocator);
00189 
00206 APR_DECLARE(apr_status_t) apr_pool_create_ex_debug(apr_pool_t **newpool,
00207                                                    apr_pool_t *parent,
00208                                                    apr_abortfunc_t abort_fn,
00209                                                    apr_allocator_t *allocator,
00210                                                    const char *file_line);
00211 
00212 #if APR_POOL_DEBUG
00213 #define apr_pool_create_ex(newpool, parent, abort_fn, allocator)  \
00214     apr_pool_create_ex_debug(newpool, parent, abort_fn, allocator, \
00215                              APR_POOL__FILE_LINE__)
00216 #endif
00217 
00226 #if defined(DOXYGEN)
00227 APR_DECLARE(apr_status_t) apr_pool_create(apr_pool_t **newpool,
00228                                           apr_pool_t *parent);
00229 #else
00230 #if APR_POOL_DEBUG
00231 #define apr_pool_create(newpool, parent) \
00232     apr_pool_create_ex_debug(newpool, parent, NULL, NULL, \
00233                              APR_POOL__FILE_LINE__)
00234 #else
00235 #define apr_pool_create(newpool, parent) \
00236     apr_pool_create_ex(newpool, parent, NULL, NULL)
00237 #endif
00238 #endif
00239 
00241 #if APR_POOL_DEBUG
00242 #define apr_pool_sub_make(newpool, parent, abort_fn) \
00243     (void)apr_pool_create_ex_debug(newpool, parent, abort_fn, \
00244                                    NULL, \
00245                                    APR_POOL__FILE_LINE__)
00246 #else
00247 #define apr_pool_sub_make(newpool, parent, abort_fn) \
00248     (void)apr_pool_create_ex(newpool, parent, abort_fn, NULL)
00249 #endif
00250 
00255 APR_DECLARE(apr_allocator_t *) apr_pool_allocator_get(apr_pool_t *pool);
00256 
00265 APR_DECLARE(void) apr_pool_clear(apr_pool_t *p);
00266 
00280 APR_DECLARE(void) apr_pool_clear_debug(apr_pool_t *p,
00281                                        const char *file_line);
00282 
00283 #if APR_POOL_DEBUG
00284 #define apr_pool_clear(p) \
00285     apr_pool_clear_debug(p, APR_POOL__FILE_LINE__)
00286 #endif
00287 
00294 APR_DECLARE(void) apr_pool_destroy(apr_pool_t *p);
00295 
00309 APR_DECLARE(void) apr_pool_destroy_debug(apr_pool_t *p,
00310                                          const char *file_line);
00311 
00312 #if APR_POOL_DEBUG
00313 #define apr_pool_destroy(p) \
00314     apr_pool_destroy_debug(p, APR_POOL__FILE_LINE__)
00315 #endif
00316 
00317 
00318 /*
00319  * Memory allocation
00320  */
00321 
00328 APR_DECLARE(void *) apr_palloc(apr_pool_t *p, apr_size_t size);
00329 
00338 APR_DECLARE(void *) apr_palloc_debug(apr_pool_t *p, apr_size_t size,
00339                                      const char *file_line);
00340 
00341 #if APR_POOL_DEBUG
00342 #define apr_palloc(p, size) \
00343     apr_palloc_debug(p, size, APR_POOL__FILE_LINE__)
00344 #endif
00345 
00352 #if defined(DOXYGEN)
00353 APR_DECLARE(void *) apr_pcalloc(apr_pool_t *p, apr_size_t size);
00354 #elif !APR_POOL_DEBUG
00355 #define apr_pcalloc(p, size) memset(apr_palloc(p, size), 0, size)
00356 #endif
00357 
00366 APR_DECLARE(void *) apr_pcalloc_debug(apr_pool_t *p, apr_size_t size,
00367                                       const char *file_line);
00368 
00369 #if APR_POOL_DEBUG
00370 #define apr_pcalloc(p, size) \
00371     apr_pcalloc_debug(p, size, APR_POOL__FILE_LINE__)
00372 #endif
00373 
00374 
00375 /*
00376  * Pool Properties
00377  */
00378 
00387 APR_DECLARE(void) apr_pool_abort_set(apr_abortfunc_t abortfunc,
00388                                      apr_pool_t *pool);
00389 
00391 APR_DECLARE(void) apr_pool_set_abort(apr_abortfunc_t abortfunc,
00392                                      apr_pool_t *pool);
00393 
00399 APR_DECLARE(apr_abortfunc_t) apr_pool_abort_get(apr_pool_t *pool);
00400 
00402 APR_DECLARE(apr_abortfunc_t) apr_pool_get_abort(apr_pool_t *pool);
00403 
00409 APR_DECLARE(apr_pool_t *) apr_pool_parent_get(apr_pool_t *pool);
00410 
00412 APR_DECLARE(apr_pool_t *) apr_pool_get_parent(apr_pool_t *pool);
00413 
00421 APR_DECLARE(int) apr_pool_is_ancestor(apr_pool_t *a, apr_pool_t *b);
00422 
00428 APR_DECLARE(void) apr_pool_tag(apr_pool_t *pool, const char *tag);
00429 
00430 
00431 /*
00432  * User data management
00433  */
00434 
00453 APR_DECLARE(apr_status_t) apr_pool_userdata_set(
00454     const void *data,
00455     const char *key,
00456     apr_status_t (*cleanup)(void *),
00457     apr_pool_t *pool);
00458 
00478 APR_DECLARE(apr_status_t) apr_pool_userdata_setn(
00479     const void *data,
00480     const char *key,
00481     apr_status_t (*cleanup)(void *),
00482     apr_pool_t *pool);
00483 
00490 APR_DECLARE(apr_status_t) apr_pool_userdata_get(void **data, const char *key,
00491                                                 apr_pool_t *pool);
00492 
00493 
00494 /*
00495  * Cleanup
00496  *
00497  * Cleanups are performed in the reverse order they were registered.  That is:
00498  * Last In, First Out.
00499  */
00500 
00510 APR_DECLARE(void) apr_pool_cleanup_register(
00511     apr_pool_t *p,
00512     const void *data,
00513     apr_status_t (*plain_cleanup)(void *),
00514     apr_status_t (*child_cleanup)(void *));
00515 
00524 APR_DECLARE(void) apr_pool_cleanup_kill(apr_pool_t *p, const void *data,
00525                                         apr_status_t (*cleanup)(void *));
00526 
00534 APR_DECLARE(void) apr_pool_child_cleanup_set(
00535     apr_pool_t *p,
00536     const void *data,
00537     apr_status_t (*plain_cleanup)(void *),
00538     apr_status_t (*child_cleanup)(void *));
00539 
00547 APR_DECLARE(apr_status_t) apr_pool_cleanup_run(
00548     apr_pool_t *p,
00549     void *data,
00550     apr_status_t (*cleanup)(void *));
00551 
00556 APR_DECLARE_NONSTD(apr_status_t) apr_pool_cleanup_null(void *data);
00557 
00558 /* Preparing for exec() --- close files, etc., but *don't* flush I/O
00559  * buffers, *don't* wait for subprocesses, and *don't* free any memory.
00560  */
00565 APR_DECLARE(void) apr_pool_cleanup_for_exec(void);
00566 
00567 
00612 #if APR_POOL_DEBUG || defined(DOXYGEN)
00613 
00618 APR_DECLARE(void) apr_pool_join(apr_pool_t *p, apr_pool_t *sub);
00619 
00625 APR_DECLARE(apr_pool_t *) apr_pool_find(const void *mem);
00626 
00633 APR_DECLARE(apr_size_t) apr_pool_num_bytes(apr_pool_t *p, int recurse);
00634 
00640 APR_DECLARE(void) apr_pool_lock(apr_pool_t *pool, int flag);
00641 
00642 /* @} */
00643 
00644 #else /* APR_POOL_DEBUG or DOXYGEN */
00645 
00646 #ifdef apr_pool_join
00647 #undef apr_pool_join
00648 #endif
00649 #define apr_pool_join(a,b)
00650 
00651 #ifdef apr_pool_lock
00652 #undef apr_pool_lock
00653 #endif
00654 #define apr_pool_lock(pool, lock)
00655 
00656 #endif /* APR_POOL_DEBUG or DOXYGEN */
00657 
00660 #ifdef __cplusplus
00661 }
00662 #endif
00663 
00664 #endif /* !APR_POOLS_H */

Generated on Mon Nov 26 11:47:26 2007 for Apache Portable Runtime by  doxygen 1.5.2