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 
00491 APR_DECLARE(apr_status_t) apr_pool_userdata_set(
00492     const void *data,
00493     const char *key,
00494     apr_status_t (*cleanup)(void *),
00495     apr_pool_t *pool);
00496 
00516 APR_DECLARE(apr_status_t) apr_pool_userdata_setn(
00517     const void *data,
00518     const char *key,
00519     apr_status_t (*cleanup)(void *),
00520     apr_pool_t *pool);
00521 
00528 APR_DECLARE(apr_status_t) apr_pool_userdata_get(void **data, const char *key,
00529                                                 apr_pool_t *pool);
00530 
00531 
00532 /*
00533  * Cleanup
00534  *
00535  * Cleanups are performed in the reverse order they were registered.  That is:
00536  * Last In, First Out.
00537  */
00538 
00548 APR_DECLARE(void) apr_pool_cleanup_register(
00549     apr_pool_t *p,
00550     const void *data,
00551     apr_status_t (*plain_cleanup)(void *),
00552     apr_status_t (*child_cleanup)(void *));
00553 
00562 APR_DECLARE(void) apr_pool_cleanup_kill(apr_pool_t *p, const void *data,
00563                                         apr_status_t (*cleanup)(void *));
00564 
00572 APR_DECLARE(void) apr_pool_child_cleanup_set(
00573     apr_pool_t *p,
00574     const void *data,
00575     apr_status_t (*plain_cleanup)(void *),
00576     apr_status_t (*child_cleanup)(void *));
00577 
00585 APR_DECLARE(apr_status_t) apr_pool_cleanup_run(
00586     apr_pool_t *p,
00587     void *data,
00588     apr_status_t (*cleanup)(void *));
00589 
00594 APR_DECLARE_NONSTD(apr_status_t) apr_pool_cleanup_null(void *data);
00595 
00596 /* Preparing for exec() --- close files, etc., but *don't* flush I/O
00597  * buffers, *don't* wait for subprocesses, and *don't* free any memory.
00598  */
00603 APR_DECLARE(void) apr_pool_cleanup_for_exec(void);
00604 
00605 
00650 #if APR_POOL_DEBUG || defined(DOXYGEN)
00651 
00656 APR_DECLARE(void) apr_pool_join(apr_pool_t *p, apr_pool_t *sub);
00657 
00663 APR_DECLARE(apr_pool_t *) apr_pool_find(const void *mem);
00664 
00671 APR_DECLARE(apr_size_t) apr_pool_num_bytes(apr_pool_t *p, int recurse);
00672 
00678 APR_DECLARE(void) apr_pool_lock(apr_pool_t *pool, int flag);
00679 
00680 /* @} */
00681 
00682 #else /* APR_POOL_DEBUG or DOXYGEN */
00683 
00684 #ifdef apr_pool_join
00685 #undef apr_pool_join
00686 #endif
00687 #define apr_pool_join(a,b)
00688 
00689 #ifdef apr_pool_lock
00690 #undef apr_pool_lock
00691 #endif
00692 #define apr_pool_lock(pool, lock)
00693 
00694 #endif /* APR_POOL_DEBUG or DOXYGEN */
00695 
00698 #ifdef __cplusplus
00699 }
00700 #endif
00701 
00702 #endif /* !APR_POOLS_H */

Generated on Thu Feb 26 22:53:25 2004 for Apache Portable Runtime by doxygen1.2.18