Attachment 16231 Details for Bug 35975 – Clarify docs for cleanup functions

[patch] Clarify docs for cleanup functions

apr-pools_docs.patch (text/plain), 3.60 KB, created by Jonathan Wakely on 2005-08-28 12:03:31 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Jonathan Wakely

Created: 2005-08-28 12:03:31 UTC

Size: 3.60 KB

patch

obsolete

>Index: include/apr_pools.h
>===================================================================
>--- include/apr_pools.h	(revision 231517)
>+++ include/apr_pools.h	(working copy)
>@@ -476,8 +476,8 @@
>                                                 apr_pool_t *pool);
> 
> 
>-/*
>- * Cleanup
>+/**
>+ * @defgroup PoolCleanup  Pool Cleanup Functions
>  *
>  * Cleanups are performed in the reverse order they were registered.  That is:
>  * Last In, First Out.  A cleanup function can safely allocate memory from
>@@ -486,6 +486,8 @@
>  * terminates.  Cleanups have to take caution in calling functions that
>  * create subpools. Subpools, created during cleanup will NOT automatically
>  * be cleaned up.  In other words, cleanups are to clean up after themselves.
>+ *
>+ * @{
>  */
> 
> /**
>@@ -504,9 +506,13 @@
>     apr_status_t (*child_cleanup)(void *));
> 
> /**
>- * Remove a previously registered cleanup function
>- * @param p The pool remove the cleanup from
>- * @param data The data to remove from cleanup
>+ * Remove a previously registered cleanup function.
>+ * 
>+ * The cleanup most recently registered with @a p having the same values of
>+ * @a data and @a cleanup will be removed.
>+ *
>+ * @param p The pool to remove the cleanup from
>+ * @param data The data of the registered cleanup
>  * @param cleanup The function to remove from cleanup
>  * @remarks For some strange reason only the plain_cleanup is handled by this
>  *          function
>@@ -515,7 +521,12 @@
>                                         apr_status_t (*cleanup)(void *));
> 
> /**
>- * Replace the child cleanup of a previously registered cleanup
>+ * Replace the child cleanup function of a previously registered cleanup.
>+ * 
>+ * The cleanup most recently registered with @a p having the same values of
>+ * @a data and @a plain_cleanup will have the registered child cleanup
>+ * function replaced with @a child_cleanup.
>+ *
>  * @param p The pool of the registered cleanup
>  * @param data The data of the registered cleanup
>  * @param plain_cleanup The plain cleanup function of the registered cleanup
>@@ -528,9 +539,13 @@
>     apr_status_t (*child_cleanup)(void *));
> 
> /**
>- * Run the specified cleanup function immediately and unregister it. Use
>- * @a data instead of the data that was registered with the cleanup.
>- * @param p The pool remove the cleanup from
>+ * Run the specified cleanup function immediately and unregister it.
>+ *
>+ * The cleanup most recently registered with @a p having the same values of
>+ * @a data and @a cleanup will be removed and @a cleanup will be called
>+ * with @a data as the argument.
>+ *
>+ * @param p The pool to remove the cleanup from
>  * @param data The data to remove from cleanup
>  * @param cleanup The function to remove from cleanup
>  */
>@@ -540,8 +555,11 @@
>     apr_status_t (*cleanup)(void *));
> 
> /**
>- * An empty cleanup function
>- * @param data The data to cleanup
>+ * An empty cleanup function.
>+ * 
>+ * Passed to apr_pool_cleanup_register() when no cleanup is required.
>+ *
>+ * @param data The data to cleanup, will not be used by this function.
>  */
> APR_DECLARE_NONSTD(apr_status_t) apr_pool_cleanup_null(void *data);
> 
>@@ -549,11 +567,15 @@
>  * buffers, *don't* wait for subprocesses, and *don't* free any memory.
>  */
> /**
>- * Run all of the child_cleanups, so that any unnecessary files are
>- * closed because we are about to exec a new program
>+ * Run all registered child cleanups.
>+ *
>+ * Run all of the child_cleanups registered with the global pool and
>+ * all sub-pools, so that any unnecessary files are closed before we
>+ * exec a new program.
>  */
> APR_DECLARE(void) apr_pool_cleanup_for_exec(void);
> 
>+/** @} */
> 
> /**
>  * @defgroup PoolDebug Pool Debugging functions.

Actions: View | Diff

Attachments on bug 35975: 15853 | 16014 | 16231