apr_pools.h

Go to the documentation of this file.

/* Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 
#ifndef APR_POOLS_H
#define APR_POOLS_H
 
#include "apr.h"
#include "apr_errno.h"
#include "apr_general.h" /* for APR_STRINGIFY */
#define APR_WANT_MEMFUNC 
#include "apr_want.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
typedef struct apr_pool_t apr_pool_t;
 
 
#define APR_POOL_DECLARE_ACCESSOR(type) \
    APR_DECLARE(apr_pool_t *) apr_##type##_pool_get \
        (const apr_##type##_t *the##type)
 
#define APR_POOL_IMPLEMENT_ACCESSOR(type) \
    APR_DECLARE(apr_pool_t *) apr_##type##_pool_get \
            (const apr_##type##_t *the##type) \
        { return the##type->pool; }
 
 
#if defined(APR_POOL_DEBUG)
/* If APR_POOL_DEBUG is blank, we get 1; if it is a number, we get -1. */
#if (APR_POOL_DEBUG - APR_POOL_DEBUG -1 == 1)
#undef APR_POOL_DEBUG
#define APR_POOL_DEBUG 1
#endif
#else
#define APR_POOL_DEBUG 0
#endif
 
#define APR_POOL__FILE_LINE__ __FILE__ ":" APR_STRINGIFY(__LINE__)
 
 
 
typedef int (*apr_abortfunc_t)(int retcode);
 
/*
 * APR memory structure manipulators (pools, tables, and arrays).
 */
 
/*
 * Initialization
 */
 
APR_DECLARE(apr_status_t) apr_pool_initialize(void);
 
APR_DECLARE(void) apr_pool_terminate(void);
 
/*
 * Pool creation/destruction
 */
 
#include "apr_allocator.h"
 
APR_DECLARE(apr_status_t) apr_pool_create_ex(apr_pool_t **newpool,
                                             apr_pool_t *parent,
                                             apr_abortfunc_t abort_fn,
                                             apr_allocator_t *allocator)
                          __attribute__((nonnull(1)));
 
APR_DECLARE(apr_status_t) apr_pool_create_unmanaged_ex(apr_pool_t **newpool,
                                                   apr_abortfunc_t abort_fn,
                                                   apr_allocator_t *allocator)
                          __attribute__((nonnull(1)));
 
APR_DECLARE(apr_status_t) apr_pool_create_ex_debug(apr_pool_t **newpool,
                                                   apr_pool_t *parent,
                                                   apr_abortfunc_t abort_fn,
                                                   apr_allocator_t *allocator,
                                                   const char *file_line)
                          __attribute__((nonnull(1)));
 
#if APR_POOL_DEBUG
#define apr_pool_create_ex(newpool, parent, abort_fn, allocator)  \
    apr_pool_create_ex_debug(newpool, parent, abort_fn, allocator, \
                             APR_POOL__FILE_LINE__)
#endif
 
APR_DECLARE(apr_status_t) apr_pool_create_unmanaged_ex_debug(apr_pool_t **newpool,
                                                   apr_abortfunc_t abort_fn,
                                                   apr_allocator_t *allocator,
                                                   const char *file_line)
                          __attribute__((nonnull(1)));
 
#if APR_POOL_DEBUG
#define apr_pool_create_unmanaged_ex(newpool, abort_fn, allocator)  \
    apr_pool_create_unmanaged_ex_debug(newpool, abort_fn, allocator, \
                                  APR_POOL__FILE_LINE__)
 
#endif
 
#if defined(DOXYGEN)
APR_DECLARE(apr_status_t) apr_pool_create(apr_pool_t **newpool,
                                          apr_pool_t *parent);
#else
#if APR_POOL_DEBUG
#define apr_pool_create(newpool, parent) \
    apr_pool_create_ex_debug(newpool, parent, NULL, NULL, \
                             APR_POOL__FILE_LINE__)
#else
#define apr_pool_create(newpool, parent) \
    apr_pool_create_ex(newpool, parent, NULL, NULL)
#endif
#endif
 
#if defined(DOXYGEN)
APR_DECLARE(apr_status_t) apr_pool_create_unmanaged(apr_pool_t **newpool);
#else
#if APR_POOL_DEBUG
#define apr_pool_create_unmanaged(newpool) \
    apr_pool_create_unmanaged_ex_debug(newpool, NULL, NULL, \
                                  APR_POOL__FILE_LINE__)
#else
#define apr_pool_create_unmanaged(newpool) \
    apr_pool_create_unmanaged_ex(newpool, NULL, NULL)
#endif
#endif
 
APR_DECLARE(apr_allocator_t *) apr_pool_allocator_get(apr_pool_t *pool)
                               __attribute__((nonnull(1)));
 
APR_DECLARE(void) apr_pool_clear(apr_pool_t *p) __attribute__((nonnull(1)));
 
APR_DECLARE(void) apr_pool_clear_debug(apr_pool_t *p,
                                       const char *file_line)
                  __attribute__((nonnull(1)));
 
#if APR_POOL_DEBUG
#define apr_pool_clear(p) \
    apr_pool_clear_debug(p, APR_POOL__FILE_LINE__)
#endif
 
APR_DECLARE(void) apr_pool_destroy(apr_pool_t *p) __attribute__((nonnull(1)));
 
APR_DECLARE(void) apr_pool_destroy_debug(apr_pool_t *p,
                                         const char *file_line)
                  __attribute__((nonnull(1)));
 
#if APR_POOL_DEBUG
#define apr_pool_destroy(p) \
    apr_pool_destroy_debug(p, APR_POOL__FILE_LINE__)
#endif
 
 
/*
 * Memory allocation
 */
 
APR_DECLARE(void *) apr_palloc(apr_pool_t *p, apr_size_t size)
#if defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4))
                    __attribute__((alloc_size(2)))
#endif
                    __attribute__((nonnull(1)));
 
APR_DECLARE(void *) apr_palloc_debug(apr_pool_t *p, apr_size_t size,
                                     const char *file_line)
#if defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4))
                    __attribute__((alloc_size(2)))
#endif
                    __attribute__((nonnull(1)));
 
#if APR_POOL_DEBUG
#define apr_palloc(p, size) \
    apr_palloc_debug(p, size, APR_POOL__FILE_LINE__)
#endif
 
#if defined(DOXYGEN)
APR_DECLARE(void *) apr_pcalloc(apr_pool_t *p, apr_size_t size);
#elif !APR_POOL_DEBUG
#define apr_pcalloc(p, size) memset(apr_palloc(p, size), 0, size)
#endif
 
APR_DECLARE(void *) apr_pcalloc_debug(apr_pool_t *p, apr_size_t size,
                                      const char *file_line)
                    __attribute__((nonnull(1)));
 
#if APR_POOL_DEBUG
#define apr_pcalloc(p, size) \
    apr_pcalloc_debug(p, size, APR_POOL__FILE_LINE__)
#endif
 
 
/*
 * Pool Properties
 */
 
APR_DECLARE(void) apr_pool_abort_set(apr_abortfunc_t abortfunc,
                                     apr_pool_t *pool)
                  __attribute__((nonnull(2)));
 
APR_DECLARE(apr_abortfunc_t) apr_pool_abort_get(apr_pool_t *pool)
                             __attribute__((nonnull(1)));
 
APR_DECLARE(apr_pool_t *) apr_pool_parent_get(apr_pool_t *pool)
                          __attribute__((nonnull(1)));
 
APR_DECLARE(int) apr_pool_is_ancestor(apr_pool_t *a, apr_pool_t *b);
 
APR_DECLARE(void) apr_pool_tag(apr_pool_t *pool, const char *tag)
                  __attribute__((nonnull(1)));
 
APR_DECLARE(const char *) apr_pool_get_tag(apr_pool_t *pool)
                  __attribute__((nonnull(1)));
 
/*
 * User data management
 */
 
APR_DECLARE(apr_status_t) apr_pool_userdata_set(const void *data,
                                                const char *key,
                                                apr_status_t (*cleanup)(void *),
                                                apr_pool_t *pool)
                          __attribute__((nonnull(2,4)));
 
APR_DECLARE(apr_status_t) apr_pool_userdata_setn(
                                const void *data, const char *key,
                                apr_status_t (*cleanup)(void *),
                                apr_pool_t *pool)
                          __attribute__((nonnull(2,4)));
 
APR_DECLARE(apr_status_t) apr_pool_userdata_get(void **data, const char *key,
                                                apr_pool_t *pool)
                          __attribute__((nonnull(1,2,3)));
 
 
APR_DECLARE(void) apr_pool_cleanup_register(
                            apr_pool_t *p, const void *data,
                            apr_status_t (*plain_cleanup)(void *),
                            apr_status_t (*child_cleanup)(void *))
                  __attribute__((nonnull(3,4)));
 
APR_DECLARE(void) apr_pool_pre_cleanup_register(
                            apr_pool_t *p, const void *data,
                            apr_status_t (*plain_cleanup)(void *))
                  __attribute__((nonnull(3)));
 
APR_DECLARE(void) apr_pool_cleanup_kill(apr_pool_t *p, const void *data,
                                        apr_status_t (*cleanup)(void *))
                  __attribute__((nonnull(3)));
 
APR_DECLARE(void) apr_pool_child_cleanup_set(
                        apr_pool_t *p, const void *data,
                        apr_status_t (*plain_cleanup)(void *),
                        apr_status_t (*child_cleanup)(void *))
                  __attribute__((nonnull(3,4)));
 
APR_DECLARE(apr_status_t) apr_pool_cleanup_run(apr_pool_t *p, void *data,
                                               apr_status_t (*cleanup)(void *))
                          __attribute__((nonnull(3)));
 
APR_DECLARE_NONSTD(apr_status_t) apr_pool_cleanup_null(void *data);
 
APR_DECLARE(void) apr_pool_cleanup_for_exec(void);
 
APR_DECLARE(void) apr_pool_owner_set(apr_pool_t *pool, apr_uint32_t flags);
 
APR_DECLARE(void) apr_pool_join(apr_pool_t *p, apr_pool_t *sub)
                  __attribute__((nonnull(2)));
 
APR_DECLARE(apr_pool_t *) apr_pool_find(const void *mem);
 
APR_DECLARE(apr_size_t) apr_pool_num_bytes(apr_pool_t *p, int recurse)
                        __attribute__((nonnull(1)));
 
APR_DECLARE(void) apr_pool_lock(apr_pool_t *pool, int flag);
 
#ifdef __cplusplus
}
#endif
 
#endif /* !APR_POOLS_H */