| /* svn_pools.h: APR pool management for Subversion |
| * |
| * ==================================================================== |
| * Copyright (c) 2000-2002 CollabNet. All rights reserved. |
| * |
| * This software is licensed as described in the file COPYING, which |
| * you should have received as part of this distribution. The terms |
| * are also available at http://subversion.tigris.org/license-1.html. |
| * If newer versions of this license are posted there, you may use a |
| * newer version instead, at your option. |
| * |
| * This software consists of voluntary contributions made by many |
| * individuals. For exact contribution history, see the revision |
| * history and logs, available at http://subversion.tigris.org/. |
| * ==================================================================== |
| */ |
| |
| |
| |
| |
| #ifndef SVN_POOLS_H |
| #define SVN_POOLS_H |
| |
| #include <apr.h> |
| #include <apr_errno.h> /* APR's error system */ |
| #include <apr_pools.h> |
| |
| #include <svn_types.h> |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif /* __cplusplus */ |
| |
| |
| |
| /*** Wrappers around APR pools, so we get error pools. ***/ |
| |
| |
| /* THE ERROR POOL |
| * |
| * When SVN allocates an svn_error_t, it must do so from a pool. There is |
| * almost always a pool available for a function to provide to the error |
| * creation functions. However, that pool may have a shorter lifetime than |
| * is required for the error (in many cases, the error needs to bubble all |
| * the way to the top-most control function). Assuming that these shorter- |
| * lifetime pools are cleared or even destroyed as the error propagates, |
| * then we need a way to ensure that the error is allocated within the |
| * proper pool, to get the proper lifetime. |
| * |
| * We create a pool specifically for errors. This pool is then "hung from" |
| * the top-most pool that SVN will be using (whether this top-most pool is |
| * provided by an embeddor such as Apache, or whether an SVN tool creates |
| * the top-most pool itself). Since this error pool has a lifetime *at least* |
| * as long as the top-most pool, then any errors allocated within it will |
| * survive back to the top-most control function. |
| * |
| * We use a subpool rather than the top-most pool itself because we may want |
| * to occasionally clear the error pool (say, if we get an error, recover, |
| * and restart the operation). |
| * |
| * This subpool is called "the error pool". Using APR's "userdata" feature, |
| * we associate the error pool with every subpool that SVN creates. When |
| * the SVN error system allocates a new error, it first fetches the subpool |
| * from the pool.. |
| */ |
| |
| /* You may be wondering why is this is in svn_error, instead of |
| svn_pool or whatever. The reason is the needs of the SVN error |
| system are our only justification for wrapping APR's pool creation |
| funcs -- because errors have to live as long as the top-most pool |
| in a test program or a `request'. If you're not using SVN errors, |
| there's no reason not to use APR's native pool interface. But you |
| are using SVN errors, aren't you? */ |
| |
| /* Initalize the given pool as SVN's top-most pool. This is needed when SVN |
| * is embedded in another application, and all of SVN's work will occur |
| * within a given pool. |
| * |
| * This function will construct the error pool (for all errors to live |
| * within), and hang it off of the given pool. When subpools are created |
| * with svn_pool_create(), they will inherit the error pool. |
| * |
| * Note: we return an apr_status_t since a catch-22 means we cannot allocate |
| * an svn_error_t. |
| * |
| * WARNING: this is ONLY to be used for pools provided by an embeddor. Do not |
| * use it for pools returned by svn_pool_create(). */ |
| apr_status_t svn_error_init_pool (apr_pool_t *top_pool); |
| |
| |
| /* Return a new pool. If PARENT_POOL is non-null, then the new |
| * pool will be a subpool of it, and will inherit the containing |
| * pool's dedicated error subpool. |
| * |
| * If PARENT_POOL is NULL, then the returned pool will be a new |
| * "global" pool (with no parent), and an error pool will be created. |
| * |
| * If anything goes wrong with the pool creation, then an abort function |
| * will be called, which will exit the program. If future allocations from |
| * this pool cannot be fulfilled, then the abort function will be called, |
| * terminating the program. */ |
| apr_pool_t *svn_pool_create (apr_pool_t *parent_pool); |
| |
| apr_pool_t *svn_pool_create_debug (apr_pool_t *parent_pool, |
| const char *file_line); |
| |
| #if APR_POOL_DEBUG |
| #define svn_pool_create(p) svn_pool_create_debug(p, APR_POOL__FILE_LINE__) |
| #endif /* APR_POOL_DEBUG */ |
| |
| |
| /* Clear the passed in pool. |
| * |
| * The reason we need this wrapper to apr_pool_clear, is because |
| * apr_pool_clear removes the association with the appropriate error |
| * pool. This wrapper calls apr_pool_clear, and then reattaches or |
| * recreates the error pool. |
| * |
| * If anything goes wrong, an abort function will be called. */ |
| void svn_pool_clear (apr_pool_t *p); |
| |
| void svn_pool_clear_debug (apr_pool_t *p, |
| const char *file_line); |
| |
| #if APR_POOL_DEBUG |
| #define svn_pool_clear(p) svn_pool_clear_debug(p, APR_POOL__FILE_LINE__) |
| #endif /* APR_POOL_DEBUG */ |
| |
| |
| /* Destroy a POOL and all of its children. |
| * |
| * This define for svn_pool_destroy exists for symmatry (the |
| * not-so-grand reason) and for the existence of a great memory usage |
| * debugging hook (the grand reason). |
| */ |
| #define svn_pool_destroy apr_pool_destroy |
| |
| |
| #ifdef __cplusplus |
| } |
| #endif /* __cplusplus */ |
| |
| #endif /* SVN_ERROR_H */ |
| |
| |
| /* ---------------------------------------------------------------- |
| * local variables: |
| * eval: (load-file "../../tools/dev/svn-dev.el") |
| * end: |
| */ |