GME  13
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 
00043 #include "apr.h"
00044 #include "apr_errno.h"
00045 #include "apr_general.h" /* for APR_STRINGIFY */
00046 #define APR_WANT_MEMFUNC 
00047 #include "apr_want.h"
00048 
00049 #ifdef __cplusplus
00050 extern "C" {
00051 #endif
00052 
00060 typedef struct apr_pool_t apr_pool_t;
00061 
00062 
00081 #define APR_POOL_DECLARE_ACCESSOR(type) \
00082     APR_DECLARE(apr_pool_t *) apr_##type##_pool_get \
00083         (const apr_##type##_t *the##type)
00084 
00091 #define APR_POOL_IMPLEMENT_ACCESSOR(type) \
00092     APR_DECLARE(apr_pool_t *) apr_##type##_pool_get \
00093             (const apr_##type##_t *the##type) \
00094         { return the##type->pool; }
00095 
00096 
00132 #if defined(APR_POOL_DEBUG)
00133 /* If APR_POOL_DEBUG is blank, we get 1; if it is a number, we get -1. */
00134 #if (APR_POOL_DEBUG - APR_POOL_DEBUG -1 == 1)
00135 #undef APR_POOL_DEBUG
00136 #define APR_POOL_DEBUG 1
00137 #endif
00138 #else
00139 #define APR_POOL_DEBUG 0
00140 #endif
00141 
00143 #define APR_POOL__FILE_LINE__ __FILE__ ":" APR_STRINGIFY(__LINE__)
00144 
00145 
00146 
00148 typedef int (*apr_abortfunc_t)(int retcode);
00149 
00150 /*
00151  * APR memory structure manipulators (pools, tables, and arrays).
00152  */
00153 
00154 /*
00155  * Initialization
00156  */
00157 
00164 APR_DECLARE(apr_status_t) apr_pool_initialize(void);
00165 
00172 APR_DECLARE(void) apr_pool_terminate(void);
00173 
00174 
00175 /*
00176  * Pool creation/destruction
00177  */
00178 
00179 #include "apr_allocator.h"
00180 
00196 APR_DECLARE(apr_status_t) apr_pool_create_ex(apr_pool_t **newpool,
00197                                              apr_pool_t *parent,
00198                                              apr_abortfunc_t abort_fn,
00199                                              apr_allocator_t *allocator)
00200                           __attribute__((nonnull(1)));
00201 
00206 APR_DECLARE(apr_status_t) apr_pool_create_core_ex(apr_pool_t **newpool,
00207                                                   apr_abortfunc_t abort_fn,
00208                                                   apr_allocator_t *allocator);
00209 
00222 APR_DECLARE(apr_status_t) apr_pool_create_unmanaged_ex(apr_pool_t **newpool,
00223                                                    apr_abortfunc_t abort_fn,
00224                                                    apr_allocator_t *allocator)
00225                           __attribute__((nonnull(1)));
00226 
00243 APR_DECLARE(apr_status_t) apr_pool_create_ex_debug(apr_pool_t **newpool,
00244                                                    apr_pool_t *parent,
00245                                                    apr_abortfunc_t abort_fn,
00246                                                    apr_allocator_t *allocator,
00247                                                    const char *file_line)
00248                           __attribute__((nonnull(1)));
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 
00260 APR_DECLARE(apr_status_t) apr_pool_create_core_ex_debug(apr_pool_t **newpool,
00261                                                    apr_abortfunc_t abort_fn,
00262                                                    apr_allocator_t *allocator,
00263                                                    const char *file_line);
00264 
00280 APR_DECLARE(apr_status_t) apr_pool_create_unmanaged_ex_debug(apr_pool_t **newpool,
00281                                                    apr_abortfunc_t abort_fn,
00282                                                    apr_allocator_t *allocator,
00283                                                    const char *file_line)
00284                           __attribute__((nonnull(1)));
00285 
00286 #if APR_POOL_DEBUG
00287 #define apr_pool_create_core_ex(newpool, abort_fn, allocator)  \
00288     apr_pool_create_unmanaged_ex_debug(newpool, abort_fn, allocator, \
00289                                   APR_POOL__FILE_LINE__)
00290 
00291 #define apr_pool_create_unmanaged_ex(newpool, abort_fn, allocator)  \
00292     apr_pool_create_unmanaged_ex_debug(newpool, abort_fn, allocator, \
00293                                   APR_POOL__FILE_LINE__)
00294 
00295 #endif
00296 
00309 #if defined(DOXYGEN)
00310 APR_DECLARE(apr_status_t) apr_pool_create(apr_pool_t **newpool,
00311                                           apr_pool_t *parent);
00312 #else
00313 #if APR_POOL_DEBUG
00314 #define apr_pool_create(newpool, parent) \
00315     apr_pool_create_ex_debug(newpool, parent, NULL, NULL, \
00316                              APR_POOL__FILE_LINE__)
00317 #else
00318 #define apr_pool_create(newpool, parent) \
00319     apr_pool_create_ex(newpool, parent, NULL, NULL)
00320 #endif
00321 #endif
00322 
00327 #if defined(DOXYGEN)
00328 APR_DECLARE(apr_status_t) apr_pool_create_core(apr_pool_t **newpool);
00329 APR_DECLARE(apr_status_t) apr_pool_create_unmanaged(apr_pool_t **newpool);
00330 #else
00331 #if APR_POOL_DEBUG
00332 #define apr_pool_create_core(newpool) \
00333     apr_pool_create_unmanaged_ex_debug(newpool, NULL, NULL, \
00334                                   APR_POOL__FILE_LINE__)
00335 #define apr_pool_create_unmanaged(newpool) \
00336     apr_pool_create_unmanaged_ex_debug(newpool, NULL, NULL, \
00337                                   APR_POOL__FILE_LINE__)
00338 #else
00339 #define apr_pool_create_core(newpool) \
00340     apr_pool_create_unmanaged_ex(newpool, NULL, NULL)
00341 #define apr_pool_create_unmanaged(newpool) \
00342     apr_pool_create_unmanaged_ex(newpool, NULL, NULL)
00343 #endif
00344 #endif
00345 
00350 APR_DECLARE(apr_allocator_t *) apr_pool_allocator_get(apr_pool_t *pool)
00351                                __attribute__((nonnull(1)));
00352 
00361 APR_DECLARE(void) apr_pool_clear(apr_pool_t *p) __attribute__((nonnull(1)));
00362 
00376 APR_DECLARE(void) apr_pool_clear_debug(apr_pool_t *p,
00377                                        const char *file_line)
00378                   __attribute__((nonnull(1)));
00379 
00380 #if APR_POOL_DEBUG
00381 #define apr_pool_clear(p) \
00382     apr_pool_clear_debug(p, APR_POOL__FILE_LINE__)
00383 #endif
00384 
00391 APR_DECLARE(void) apr_pool_destroy(apr_pool_t *p) __attribute__((nonnull(1)));
00392 
00406 APR_DECLARE(void) apr_pool_destroy_debug(apr_pool_t *p,
00407                                          const char *file_line)
00408                   __attribute__((nonnull(1)));
00409 
00410 #if APR_POOL_DEBUG
00411 #define apr_pool_destroy(p) \
00412     apr_pool_destroy_debug(p, APR_POOL__FILE_LINE__)
00413 #endif
00414 
00415 
00416 /*
00417  * Memory allocation
00418  */
00419 
00426 APR_DECLARE(void *) apr_palloc(apr_pool_t *p, apr_size_t size)
00427 #if defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4))
00428                     __attribute__((alloc_size(2)))
00429 #endif
00430                     __attribute__((nonnull(1)));
00431 
00440 APR_DECLARE(void *) apr_palloc_debug(apr_pool_t *p, apr_size_t size,
00441                                      const char *file_line)
00442 #if defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4))
00443                     __attribute__((alloc_size(2)))
00444 #endif
00445                     __attribute__((nonnull(1)));
00446 
00447 #if APR_POOL_DEBUG
00448 #define apr_palloc(p, size) \
00449     apr_palloc_debug(p, size, APR_POOL__FILE_LINE__)
00450 #endif
00451 
00458 #if defined(DOXYGEN)
00459 APR_DECLARE(void *) apr_pcalloc(apr_pool_t *p, apr_size_t size);
00460 #elif !APR_POOL_DEBUG
00461 #define apr_pcalloc(p, size) memset(apr_palloc(p, size), 0, size)
00462 #endif
00463 
00472 APR_DECLARE(void *) apr_pcalloc_debug(apr_pool_t *p, apr_size_t size,
00473                                       const char *file_line)
00474                     __attribute__((nonnull(1)));
00475 
00476 #if APR_POOL_DEBUG
00477 #define apr_pcalloc(p, size) \
00478     apr_pcalloc_debug(p, size, APR_POOL__FILE_LINE__)
00479 #endif
00480 
00481 
00482 /*
00483  * Pool Properties
00484  */
00485 
00494 APR_DECLARE(void) apr_pool_abort_set(apr_abortfunc_t abortfunc,
00495                                      apr_pool_t *pool)
00496                   __attribute__((nonnull(2)));
00497 
00503 APR_DECLARE(apr_abortfunc_t) apr_pool_abort_get(apr_pool_t *pool)
00504                              __attribute__((nonnull(1)));
00505 
00511 APR_DECLARE(apr_pool_t *) apr_pool_parent_get(apr_pool_t *pool)
00512                           __attribute__((nonnull(1)));
00513 
00525 APR_DECLARE(int) apr_pool_is_ancestor(apr_pool_t *a, apr_pool_t *b);
00526 
00532 APR_DECLARE(void) apr_pool_tag(apr_pool_t *pool, const char *tag)
00533                   __attribute__((nonnull(1)));
00534 
00535 
00536 /*
00537  * User data management
00538  */
00539 
00559 APR_DECLARE(apr_status_t) apr_pool_userdata_set(const void *data,
00560                                                 const char *key,
00561                                                 apr_status_t (*cleanup)(void *),
00562                                                 apr_pool_t *pool)
00563                           __attribute__((nonnull(2,4)));
00564 
00584 APR_DECLARE(apr_status_t) apr_pool_userdata_setn(
00585                                 const void *data, const char *key,
00586                                 apr_status_t (*cleanup)(void *),
00587                                 apr_pool_t *pool)
00588                           __attribute__((nonnull(2,4)));
00589 
00596 APR_DECLARE(apr_status_t) apr_pool_userdata_get(void **data, const char *key,
00597                                                 apr_pool_t *pool)
00598                           __attribute__((nonnull(1,2,3)));
00599 
00600 
00624 APR_DECLARE(void) apr_pool_cleanup_register(
00625                             apr_pool_t *p, const void *data,
00626                             apr_status_t (*plain_cleanup)(void *),
00627                             apr_status_t (*child_cleanup)(void *))
00628                   __attribute__((nonnull(3,4)));
00629 
00642 APR_DECLARE(void) apr_pool_pre_cleanup_register(
00643                             apr_pool_t *p, const void *data,
00644                             apr_status_t (*plain_cleanup)(void *))
00645                   __attribute__((nonnull(3)));
00646 
00659 APR_DECLARE(void) apr_pool_cleanup_kill(apr_pool_t *p, const void *data,
00660                                         apr_status_t (*cleanup)(void *))
00661                   __attribute__((nonnull(3)));
00662 
00675 APR_DECLARE(void) apr_pool_child_cleanup_set(
00676                         apr_pool_t *p, const void *data,
00677                         apr_status_t (*plain_cleanup)(void *),
00678                         apr_status_t (*child_cleanup)(void *))
00679                   __attribute__((nonnull(3,4)));
00680 
00692 APR_DECLARE(apr_status_t) apr_pool_cleanup_run(apr_pool_t *p, void *data,
00693                                                apr_status_t (*cleanup)(void *))
00694                           __attribute__((nonnull(3)));
00695 
00703 APR_DECLARE_NONSTD(apr_status_t) apr_pool_cleanup_null(void *data);
00704 
00711 APR_DECLARE(void) apr_pool_cleanup_for_exec(void);
00712 
00757 #if APR_POOL_DEBUG || defined(DOXYGEN)
00758 
00763 APR_DECLARE(void) apr_pool_join(apr_pool_t *p, apr_pool_t *sub)
00764                   __attribute__((nonnull(2)));
00765 
00771 APR_DECLARE(apr_pool_t *) apr_pool_find(const void *mem);
00772 
00779 APR_DECLARE(apr_size_t) apr_pool_num_bytes(apr_pool_t *p, int recurse)
00780                         __attribute__((nonnull(1)));
00781 
00787 APR_DECLARE(void) apr_pool_lock(apr_pool_t *pool, int flag);
00788 
00789 /* @} */
00790 
00791 #else /* APR_POOL_DEBUG or DOXYGEN */
00792 
00793 #ifdef apr_pool_join
00794 #undef apr_pool_join
00795 #endif
00796 #define apr_pool_join(a,b)
00797 
00798 #ifdef apr_pool_lock
00799 #undef apr_pool_lock
00800 #endif
00801 #define apr_pool_lock(pool, lock)
00802 
00803 #endif /* APR_POOL_DEBUG or DOXYGEN */
00804 
00807 #ifdef __cplusplus
00808 }
00809 #endif
00810 
00811 #endif /* !APR_POOLS_H */