Main Page | Modules | Data Structures | File List | Data Fields | Globals | Related Pages

apr_pools.h

Go to the documentation of this file.
00001 /* ====================================================================
00002  * The Apache Software License, Version 1.1
00003  *
00004  * Copyright (c) 2000-2003 The Apache Software Foundation.  All rights
00005  * reserved.
00006  *
00007  * Redistribution and use in source and binary forms, with or without
00008  * modification, are permitted provided that the following conditions
00009  * are met:
00010  *
00011  * 1. Redistributions of source code must retain the above copyright
00012  *    notice, this list of conditions and the following disclaimer.
00013  *
00014  * 2. Redistributions in binary form must reproduce the above copyright
00015  *    notice, this list of conditions and the following disclaimer in
00016  *    the documentation and/or other materials provided with the
00017  *    distribution.
00018  *
00019  * 3. The end-user documentation included with the redistribution,
00020  *    if any, must include the following acknowledgment:
00021  *       "This product includes software developed by the
00022  *        Apache Software Foundation (http://www.apache.org/)."
00023  *    Alternately, this acknowledgment may appear in the software itself,
00024  *    if and wherever such third-party acknowledgments normally appear.
00025  *
00026  * 4. The names "Apache" and "Apache Software Foundation" must
00027  *    not be used to endorse or promote products derived from this
00028  *    software without prior written permission. For written
00029  *    permission, please contact apache@apache.org.
00030  *
00031  * 5. Products derived from this software may not be called "Apache",
00032  *    nor may "Apache" appear in their name, without prior written
00033  *    permission of the Apache Software Foundation.
00034  *
00035  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
00036  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
00037  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00038  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
00039  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
00040  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
00041  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
00042  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
00043  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
00044  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
00045  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
00046  * SUCH DAMAGE.
00047  * ====================================================================
00048  *
00049  * This software consists of voluntary contributions made by many
00050  * individuals on behalf of the Apache Software Foundation.  For more
00051  * information on the Apache Software Foundation, please see
00052  * <http://www.apache.org/>.
00053  */
00054 
00055 #ifndef APR_POOLS_H
00056 #define APR_POOLS_H
00057 
00075 #include "apr.h"
00076 #include "apr_errno.h"
00077 #include "apr_general.h" /* for APR_STRINGIFY */
00078 #define APR_WANT_MEMFUNC 
00079 #include "apr_want.h"
00080 
00081 #ifdef __cplusplus
00082 extern "C" {
00083 #endif
00084 
00092 typedef struct apr_pool_t apr_pool_t;
00093 
00094 
00113 #define APR_POOL_DECLARE_ACCESSOR(type) \
00114     APR_DECLARE(apr_pool_t *) apr_##type##_pool_get \
00115         (const apr_##type##_t *the##type)
00116 
00123 #define APR_POOL_IMPLEMENT_ACCESSOR(type) \
00124     APR_DECLARE(apr_pool_t *) apr_##type##_pool_get \
00125             (const apr_##type##_t *the##type) \
00126         { return the##type->pool; }
00127 
00128 
00164 #if defined(APR_POOL_DEBUG)
00165 #if (APR_POOL_DEBUG != 0) && (APR_POOL_DEBUG - 0 == 0)
00166 #undef APR_POOL_DEBUG
00167 #define APR_POOL_DEBUG 1
00168 #endif
00169 #else
00170 #define APR_POOL_DEBUG 0
00171 #endif
00172 
00174 #define APR_POOL__FILE_LINE__ __FILE__ ":" APR_STRINGIFY(__LINE__)
00175 
00176 
00177 
00179 typedef int (*apr_abortfunc_t)(int retcode);
00180 
00181 /*
00182  * APR memory structure manipulators (pools, tables, and arrays).
00183  */
00184 
00185 /*
00186  * Initialization
00187  */
00188 
00195 APR_DECLARE(apr_status_t) apr_pool_initialize(void);
00196 
00203 APR_DECLARE(void) apr_pool_terminate(void);
00204 
00205 
00206 /*
00207  * Pool creation/destruction
00208  */
00209 
00210 #include "apr_allocator.h"
00211 
00223 APR_DECLARE(apr_status_t) apr_pool_create_ex(apr_pool_t **newpool,
00224                                              apr_pool_t *parent,
00225                                              apr_abortfunc_t abort_fn,
00226                                              apr_allocator_t *allocator);
00227 
00244 APR_DECLARE(apr_status_t) apr_pool_create_ex_debug(apr_pool_t **newpool,
00245                                                    apr_pool_t *parent,
00246                                                    apr_abortfunc_t abort_fn,
00247                                                    apr_allocator_t *allocator,
00248                                                    const char *file_line);
00249 
00250 #if APR_POOL_DEBUG
00251 #define apr_pool_create_ex(newpool, parent, abort_fn, allocator)  \
00252     apr_pool_create_ex_debug(newpool, parent, abort_fn, allocator, \
00253                              APR_POOL__FILE_LINE__)
00254 #endif
00255 
00264 #if defined(DOXYGEN)
00265 APR_DECLARE(apr_status_t) apr_pool_create(apr_pool_t **newpool,
00266                                           apr_pool_t *parent);
00267 #else
00268 #if APR_POOL_DEBUG
00269 #define apr_pool_create(newpool, parent) \
00270     apr_pool_create_ex_debug(newpool, parent, NULL, NULL, \
00271                              APR_POOL__FILE_LINE__)
00272 #else
00273 #define apr_pool_create(newpool, parent) \
00274     apr_pool_create_ex(newpool, parent, NULL, NULL)
00275 #endif
00276 #endif
00277 
00279 #if APR_POOL_DEBUG
00280 #define apr_pool_sub_make(newpool, parent, abort_fn) \
00281     (void)apr_pool_create_ex_debug(newpool, parent, abort_fn, \
00282                                    NULL, \
00283                                    APR_POOL__FILE_LINE__)
00284 #else
00285 #define apr_pool_sub_make(newpool, parent, abort_fn) \
00286     (void)apr_pool_create_ex(newpool, parent, abort_fn, NULL)
00287 #endif
00288 
00293 APR_DECLARE(apr_allocator_t *) apr_pool_allocator_get(apr_pool_t *pool);
00294 
00303 APR_DECLARE(void) apr_pool_clear(apr_pool_t *p);
00304 
00318 APR_DECLARE(void) apr_pool_clear_debug(apr_pool_t *p,
00319                                        const char *file_line);
00320 
00321 #if APR_POOL_DEBUG
00322 #define apr_pool_clear(p) \
00323     apr_pool_clear_debug(p, APR_POOL__FILE_LINE__)
00324 #endif
00325 
00332 APR_DECLARE(void) apr_pool_destroy(apr_pool_t *p);
00333 
00347 APR_DECLARE(void) apr_pool_destroy_debug(apr_pool_t *p,
00348                                          const char *file_line);
00349 
00350 #if APR_POOL_DEBUG
00351 #define apr_pool_destroy(p) \
00352     apr_pool_destroy_debug(p, APR_POOL__FILE_LINE__)
00353 #endif
00354 
00355 
00356 /*
00357  * Memory allocation
00358  */
00359 
00366 APR_DECLARE(void *) apr_palloc(apr_pool_t *p, apr_size_t size);
00367 
00376 APR_DECLARE(void *) apr_palloc_debug(apr_pool_t *p, apr_size_t size,
00377                                      const char *file_line);
00378 
00379 #if APR_POOL_DEBUG
00380 #define apr_palloc(p, size) \
00381     apr_palloc_debug(p, size, APR_POOL__FILE_LINE__)
00382 #endif
00383 
00390 #if defined(DOXYGEN)
00391 APR_DECLARE(void *) apr_pcalloc(apr_pool_t *p, apr_size_t size);
00392 #elif !APR_POOL_DEBUG
00393 #define apr_pcalloc(p, size) memset(apr_palloc(p, size), 0, size)
00394 #endif
00395 
00404 APR_DECLARE(void *) apr_pcalloc_debug(apr_pool_t *p, apr_size_t size,
00405                                       const char *file_line);
00406 
00407 #if APR_POOL_DEBUG
00408 #define apr_pcalloc(p, size) \
00409     apr_pcalloc_debug(p, size, APR_POOL__FILE_LINE__)
00410 #endif
00411 
00412 
00413 /*
00414  * Pool Properties
00415  */
00416 
00425 APR_DECLARE(void) apr_pool_abort_set(apr_abortfunc_t abortfunc,
00426                                      apr_pool_t *pool);
00427 
00429 APR_DECLARE(void) apr_pool_set_abort(apr_abortfunc_t abortfunc,
00430                                      apr_pool_t *pool);
00431 
00437 APR_DECLARE(apr_abortfunc_t) apr_pool_abort_get(apr_pool_t *pool);
00438 
00440 APR_DECLARE(apr_abortfunc_t) apr_pool_get_abort(apr_pool_t *pool);
00441 
00447 APR_DECLARE(apr_pool_t *) apr_pool_parent_get(apr_pool_t *pool);
00448 
00450 APR_DECLARE(apr_pool_t *) apr_pool_get_parent(apr_pool_t *pool);
00451 
00459 APR_DECLARE(int) apr_pool_is_ancestor(apr_pool_t *a, apr_pool_t *b);
00460 
00466 APR_DECLARE(void) apr_pool_tag(apr_pool_t *pool, const char *tag);
00467 
00468 
00469 /*
00470  * User data management
00471  */
00472 
00489 APR_DECLARE(apr_status_t) apr_pool_userdata_set(
00490     const void *data,
00491     const char *key,
00492     apr_status_t (*cleanup)(void *),
00493     apr_pool_t *pool);
00494 
00514 APR_DECLARE(apr_status_t) apr_pool_userdata_setn(
00515     const void *data,
00516     const char *key,
00517     apr_status_t (*cleanup)(void *),
00518     apr_pool_t *pool);
00519 
00526 APR_DECLARE(apr_status_t) apr_pool_userdata_get(void **data, const char *key,
00527                                                 apr_pool_t *pool);
00528 
00529 
00530 /*
00531  * Cleanup
00532  *
00533  * Cleanups are performed in the reverse order they were registered.  That is:
00534  * Last In, First Out.
00535  */
00536 
00546 APR_DECLARE(void) apr_pool_cleanup_register(
00547     apr_pool_t *p,
00548     const void *data,
00549     apr_status_t (*plain_cleanup)(void *),
00550     apr_status_t (*child_cleanup)(void *));
00551 
00560 APR_DECLARE(void) apr_pool_cleanup_kill(apr_pool_t *p, const void *data,
00561                                         apr_status_t (*cleanup)(void *));
00562 
00570 APR_DECLARE(void) apr_pool_child_cleanup_set(
00571     apr_pool_t *p,
00572     const void *data,
00573     apr_status_t (*plain_cleanup)(void *),
00574     apr_status_t (*child_cleanup)(void *));
00575 
00583 APR_DECLARE(apr_status_t) apr_pool_cleanup_run(
00584     apr_pool_t *p,
00585     void *data,
00586     apr_status_t (*cleanup)(void *));
00587 
00592 APR_DECLARE_NONSTD(apr_status_t) apr_pool_cleanup_null(void *data);
00593 
00594 /* Preparing for exec() --- close files, etc., but *don't* flush I/O
00595  * buffers, *don't* wait for subprocesses, and *don't* free any memory.
00596  */
00601 APR_DECLARE(void) apr_pool_cleanup_for_exec(void);
00602 
00603 
00648 #if APR_POOL_DEBUG || defined(DOXYGEN)
00654 APR_DECLARE(void) apr_pool_join(apr_pool_t *p, apr_pool_t *sub);
00655 
00661 APR_DECLARE(apr_pool_t *) apr_pool_find(const void *mem);
00662 
00669 APR_DECLARE(apr_size_t) apr_pool_num_bytes(apr_pool_t *p, int recurse);
00670 
00676 APR_DECLARE(void) apr_pool_lock(apr_pool_t *pool, int flag);
00677 
00678 /* @} */
00679 
00680 #else /* APR_POOL_DEBUG or DOXYGEN */
00681 
00682 #ifdef apr_pool_join
00683 #undef apr_pool_join
00684 #endif
00685 #define apr_pool_join(a,b)
00686 
00687 #ifdef apr_pool_lock
00688 #undef apr_pool_lock
00689 #endif
00690 #define apr_pool_lock(pool, lock)
00691 
00692 #endif /* APR_POOL_DEBUG or DOXYGEN */
00693 
00696 #ifdef __cplusplus
00697 }
00698 #endif
00699 
00700 #endif /* !APR_POOLS_H */

Generated on Mon Jul 4 13:03:56 2005 for Apache Portable Runtime by  doxygen 1.3.9.1