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 != 0) && (APR_POOL_DEBUG - 0 == 0)
#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);

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);

#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

#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 APR_POOL_DEBUG
#define apr_pool_sub_make(newpool, parent, abort_fn) \
    (void)apr_pool_create_ex_debug(newpool, parent, abort_fn, \
                                   NULL, \
                                   APR_POOL__FILE_LINE__)
#else
#define apr_pool_sub_make(newpool, parent, abort_fn) \
    (void)apr_pool_create_ex(newpool, parent, abort_fn, NULL)
#endif

APR_DECLARE(apr_allocator_t *) apr_pool_allocator_get(apr_pool_t *pool);

APR_DECLARE(void) apr_pool_clear(apr_pool_t *p);

APR_DECLARE(void) apr_pool_clear_debug(apr_pool_t *p,
                                       const char *file_line);

#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);

APR_DECLARE(void) apr_pool_destroy_debug(apr_pool_t *p,
                                         const char *file_line);

#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);

APR_DECLARE(void *) apr_palloc_debug(apr_pool_t *p, apr_size_t size,
                                     const char *file_line);

#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);

#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);

APR_DECLARE(void) apr_pool_set_abort(apr_abortfunc_t abortfunc,
                                     apr_pool_t *pool);

APR_DECLARE(apr_abortfunc_t) apr_pool_abort_get(apr_pool_t *pool);

APR_DECLARE(apr_abortfunc_t) apr_pool_get_abort(apr_pool_t *pool);

APR_DECLARE(apr_pool_t *) apr_pool_parent_get(apr_pool_t *pool);

APR_DECLARE(apr_pool_t *) apr_pool_get_parent(apr_pool_t *pool);

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);


/*
 * 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);

APR_DECLARE(apr_status_t) apr_pool_userdata_setn(
    const void *data,
    const char *key,
    apr_status_t (*cleanup)(void *),
    apr_pool_t *pool);

APR_DECLARE(apr_status_t) apr_pool_userdata_get(void **data, const char *key,
                                                apr_pool_t *pool);


/*
 * Cleanup
 *
 * Cleanups are performed in the reverse order they were registered.  That is:
 * Last In, First Out.
 */

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 *));

APR_DECLARE(void) apr_pool_cleanup_kill(apr_pool_t *p, const void *data,
                                        apr_status_t (*cleanup)(void *));

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 *));

APR_DECLARE(apr_status_t) apr_pool_cleanup_run(
    apr_pool_t *p,
    void *data,
    apr_status_t (*cleanup)(void *));

APR_DECLARE_NONSTD(apr_status_t) apr_pool_cleanup_null(void *data);

/* Preparing for exec() --- close files, etc., but *don't* flush I/O
 * buffers, *don't* wait for subprocesses, and *don't* free any memory.
 */
APR_DECLARE(void) apr_pool_cleanup_for_exec(void);


#if APR_POOL_DEBUG || defined(DOXYGEN)

APR_DECLARE(void) apr_pool_join(apr_pool_t *p, apr_pool_t *sub);

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);

APR_DECLARE(void) apr_pool_lock(apr_pool_t *pool, int flag);

/* @} */

#else /* APR_POOL_DEBUG or DOXYGEN */

#ifdef apr_pool_join
#undef apr_pool_join
#endif
#define apr_pool_join(a,b)

#ifdef apr_pool_lock
#undef apr_pool_lock
#endif
#define apr_pool_lock(pool, lock)

#endif /* APR_POOL_DEBUG or DOXYGEN */

#ifdef __cplusplus
}
#endif

#endif /* !APR_POOLS_H */

---