You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@apr.apache.org by be...@apache.org on 2001/03/12 00:24:57 UTC
cvs commit: apr/lib apr_pools.c
ben 01/03/11 15:24:57
Modified: docs doxygen.conf
include httpd.h
include apr.h.in apr_pools.h
lib apr_pools.c
Log:
More doxygenation.
Revision Changes Path
1.2 +6 -0 httpd-2.0/docs/doxygen.conf
Index: doxygen.conf
===================================================================
RCS file: /home/cvs/httpd-2.0/docs/doxygen.conf,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- doxygen.conf 2001/03/11 14:54:13 1.1
+++ doxygen.conf 2001/03/11 23:24:56 1.2
@@ -9,5 +9,11 @@
MACRO_EXPANSION=YES
EXPAND_ONLY_PREDEF=YES
EXPAND_AS_DEFINED=AP_DECLARE
+# not sure why this doesn't work as EXPAND_AS_DEFINED, it should!
+PREDEFINED=APR_DECLARE(x)=x APR_DECLARE_NONSTD(x)=x
OPTIMIZE_OUTPUT_FOR_C=YES
+
+FULL_PATH_NAMES=YES
+# some autoconf guru needs to make configure set this correctly...
+STRIP_FROM_PATH=/usr/home/ben/work/httpd-2.0
1.142 +2 -2 httpd-2.0/include/httpd.h
Index: httpd.h
===================================================================
RCS file: /home/cvs/httpd-2.0/include/httpd.h,v
retrieving revision 1.141
retrieving revision 1.142
diff -u -r1.141 -r1.142
--- httpd.h 2001/03/11 14:54:13 1.141
+++ httpd.h 2001/03/11 23:24:56 1.142
@@ -60,8 +60,8 @@
#define APACHE_HTTPD_H
/**
- * \file httpd.h
- * \brief HTTP Daemon routines
+ * @file httpd.h
+ * @brief HTTP Daemon routines
*/
/* XXX - We need to push more stuff to other .h files, or even .c files, to
1.75 +5 -0 apr/include/apr.h.in
Index: apr.h.in
===================================================================
RCS file: /home/cvs/apr/include/apr.h.in,v
retrieving revision 1.74
retrieving revision 1.75
diff -u -r1.74 -r1.75
--- apr.h.in 2001/03/01 13:41:46 1.74
+++ apr.h.in 2001/03/11 23:24:56 1.75
@@ -1,6 +1,11 @@
#ifndef APR_H
#define APR_H
+/**
+ * @file apr.h
+ * @brief Basic APR header
+ */
+
/* So that we can use inline on some critical functions, and use
* GNUC attributes (such as to get -Wall warnings for printf-like
* functions). Only do this in gcc 2.7 or later ... it may work
1.45 +51 -73 apr/include/apr_pools.h
Index: apr_pools.h
===================================================================
RCS file: /home/cvs/apr/include/apr_pools.h,v
retrieving revision 1.44
retrieving revision 1.45
diff -u -r1.44 -r1.45
--- apr_pools.h 2001/02/19 02:06:59 1.44
+++ apr_pools.h 2001/03/11 23:24:56 1.45
@@ -60,10 +60,9 @@
#endif
/**
- * @package APR memory allocation
- */
-
-/*
+ * @file apr_pools.h
+ * @brief APR memory allocation
+ *
* Resource allocation routines...
*
* designed so that we don't have to keep track of EVERYTHING so that
@@ -75,13 +74,6 @@
* transaction info, and one for config info. When a transaction is over,
* we can delete everything in the per-transaction apr_pool_t without fear,
* and without thinking too hard about it either.
- *
- * rst
- */
-
-/* Arenas for configuration info and transaction info
- * --- actual layout of the apr_pool_t structure is private to
- * alloc.c.
*/
#include "apr.h"
@@ -103,9 +95,7 @@
#define ALLOC_STATS
*/
-/**
- * @package APR memory allocation
- */
+/** The fundamental pool type */
typedef struct apr_pool_t apr_pool_t;
/** The memory allocation structure
@@ -134,16 +124,12 @@
void *allocation_list;
#endif
#ifdef APR_POOL_DEBUG
- /** a list of joined pools
- * @defvar apr_pool_t *joined */
+ /** a list of joined pools */
struct apr_pool_t *joined;
#endif
- /** A function to control how pools behave when they receive ENOMEM
- * @deffunc int (*apr_abort)(int retcode) */
+ /** A function to control how pools behave when they receive ENOMEM */
int (*apr_abort)(int retcode);
- /**
- * A place to hold user data associated with this pool
- * @defvar apr_hash_t *prog_data */
+ /** A place to hold user data associated with this pool */
struct apr_hash_t *prog_data;
};
@@ -194,14 +180,13 @@
* @param b The pool to search for
* @return True if a is an ancestor of b, NULL is considered an ancestor
* of all pools.
- * @deffunc int apr_pool_is_ancestor(apr_pool_t *a, apr_pool_t *b)
*/
APR_DECLARE(int) apr_pool_is_ancestor(apr_pool_t *a, apr_pool_t *b);
#else
-#ifdef apr_pool_join
-#undef apr_pool_join
-#endif
-#define apr_pool_join(a,b)
+# ifdef apr_pool_join
+# undef apr_pool_join
+# endif
+# define apr_pool_join(a,b)
#endif
/*
@@ -210,23 +195,23 @@
/**
* Setup all of the internal structures required to use pools
- * @parm globalp The apr global pool, used to allocate APR structures
+ * @param globalp The APR global pool, used to allocate APR structures
* before any other pools are created. This pool should not
* ever be used outside of APR.
- * @tip Programs do NOT need to call this directly. APR will call this
+ * @remark Programs do NOT need to call this directly. APR will call this
* automatically from apr_initialize.
- * @deffunc apr_status_t apr_pool_alloc_init(apr_pool_t *globalp)
+ * @internal
*/
APR_DECLARE(apr_status_t) apr_pool_alloc_init(apr_pool_t *globalp);
/**
* Tear down all of the internal structures required to use pools
- * @parm globalp The apr global pool, used to allocate APR structures
+ * @param globalp The APR global pool, used to allocate APR structures
* before any other pools are created. This pool should not
* ever be used outside of APR.
- * @tip Programs do NOT need to call this directly. APR will call this
+ * @remark Programs do NOT need to call this directly. APR will call this
* automatically from apr_terminate.
- * @deffunc void apr_pool_alloc_term(apr_pool_t *globalp)
+ * @internal
*/
APR_DECLARE(void) apr_pool_alloc_term(apr_pool_t *globalp);
@@ -239,7 +224,6 @@
* pool. If it is non-NULL, the new pool will inherit all
* of it's parent pool's attributes, except the apr_pool_t will
* be a sub-pool.
- * @deffunc apr_status_t apr_pool_create(apr_pool_t **newcont, apr_pool_t *cont)
*/
APR_DECLARE(apr_status_t) apr_pool_create(apr_pool_t **newcont,
apr_pool_t *cont);
@@ -248,91 +232,86 @@
* Set the data associated with the current pool
* @param data The user data associated with the pool.
* @param key The key to use for association
- * @param cleanup The cleanup program to use to cleanup the data;
- * @param cont The current pool.
- * @tip The data to be attached to the pool should have the same
- * life span as the pool it is being attached to.
+ * @param cleanup The cleanup program to use to cleanup the data
+ * @param cont The current pool
+ * @warning The data to be attached to the pool should have a life span
+ * at least as long as the pool it is being attached to.
*
* Users of APR must take EXTREME care when choosing a key to
* use for their data. It is possible to accidentally overwrite
* data by choosing a key that another part of the program is using
* It is advised that steps are taken to ensure that a unique
* key is used at all times.
- * @deffunc apr_status_t apr_pool_userdata_set(const void *data, const char *key, apr_status_t (*cleanup)(void *), apr_pool_t *cont)
+ * @bug Specify how to ensure this uniqueness!
*/
-APR_DECLARE(apr_status_t) apr_pool_userdata_set(const void *data, const char *key,
- apr_status_t (*cleanup)(void *),
- apr_pool_t *cont);
+APR_DECLARE(apr_status_t) apr_pool_userdata_set(const void *data,
+ const char *key,
+ apr_status_t (*cleanup)(void *),
+ apr_pool_t *cont);
/**
* Return the data associated with the current pool.
- * @param data The key for the data to retrieve
- * @param key The user data associated with the pool.
+ * @param data The user data associated with the pool.
+ * @param key The key for the data to retrieve
* @param cont The current pool.
- * @deffunc apr_status_t apr_pool_userdata_get(void **data, const char *key, apr_pool_t *cont)
*/
APR_DECLARE(apr_status_t) apr_pool_userdata_get(void **data, const char *key,
apr_pool_t *cont);
/**
- * make a sub pool from the current pool
+ * Make a sub pool from the current pool
* @param p The pool to use as a parent pool
* @param apr_abort A function to use if the pool cannot allocate more memory.
* @return The new sub-pool
- * @tip The apr_abort function provides a way to quit the program if the
+ * @remark The @a apr_abort function provides a way to quit the program if the
* machine is out of memory. By default, APR will return on error.
- * @deffunc apr_pool_t *apr_pool_sub_make(apr_pool_t *p, int (*apr_abort)(int retcode))
*/
APR_DECLARE(apr_pool_t *) apr_pool_sub_make(apr_pool_t *p,
int (*apr_abort)(int retcode));
/**
- * clear all memory in the pool
+ * Clear all memory in the pool and run all the cleanups. This also clears all
+ * subpools.
* @param p The pool to clear
- * @tip This does not actually free the memory, it just allows the pool
+ * @remark This does not actually free the memory, it just allows the pool
* to re-use this memory for the next allocation.
- * @deffunc void apr_pool_clear(apr_pool_t *p)
+ * @see apr_pool_destroy()
*/
APR_DECLARE(void) apr_pool_clear(apr_pool_t *p);
/**
- * destroy the pool
+ * Destroy the pool. This runs apr_pool_clear() and then frees all the memory.
* @param p The pool to destroy
- * @tip This will actually free the memory
- * @deffunc void apr_pool_destroy(apr_pool_t *p)
+ * @remark This will actually free the memory
*/
APR_DECLARE(void) apr_pool_destroy(apr_pool_t *p);
/**
- * report the number of bytes currently in the pool
+ * Report the number of bytes currently in the pool
* @param p The pool to inspect
* @return The number of bytes
- * @deffunc apr_size_t apr_pool_num_bytes(apr_pool_t *p)
*/
APR_DECLARE(apr_size_t) apr_pool_num_bytes(apr_pool_t *p);
/**
- * report the number of bytes currently in the list of free blocks
+ * Report the number of bytes currently in the list of free blocks
* @return The number of bytes
- * @deffunc apr_size_t apr_pool_free_blocks_num_bytes(void)
*/
APR_DECLARE(apr_size_t) apr_pool_free_blocks_num_bytes(void);
/**
* Allocate a block of memory from a pool
- * @param c The pool to allocate out of
+ * @param c The pool to allocate from
* @param reqsize The amount of memory to allocate
* @return The allocated memory
- * @deffunc void *apr_palloc(apr_pool_t *c, apr_size_t reqsize)
*/
APR_DECLARE(void *) apr_palloc(apr_pool_t *c, apr_size_t reqsize);
/**
* Allocate a block of memory from a pool and set all of the memory to 0
- * @param p The pool to allocate out of
+ * @param p The pool to allocate from
* @param size The amount of memory to allocate
* @return The allocated memory
- * @deffunc void *apr_pcalloc(apr_pool_t *p, apr_size_t size)
*/
APR_DECLARE(void *) apr_pcalloc(apr_pool_t *p, apr_size_t size);
@@ -342,29 +321,30 @@
* @param data The data to pass to the cleanup function.
* @param plain_cleanup The function to call when the pool is cleared
* or destroyed
- * @param child_cleanup The function to call when a child process is created
- * @deffunc void apr_pool_cleanup_register(apr_pool_t *p, const void *data, apr_status_t (*plain_cleanup)(void *), apr_status_t (*child_cleanup)(void *))
+ * @param child_cleanup The function to call when a child process is created -
+ * this function is called in the child, obviously!
*/
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 *));
/**
- * remove a previously registered cleanup function
+ * Remove a previously registered cleanup function
* @param p The pool remove the cleanup from
* @param data The data to remove from cleanup
* @param cleanup The function to remove from cleanup
- * @deffunc void apr_pool_cleanup_kill(apr_pool_t *p, const void *data, apr_status_t (*cleanup)(void *))
+ * @remarks For some strange reason only the plain_cleanup is handled by this
+ * function
*/
APR_DECLARE(void) apr_pool_cleanup_kill(apr_pool_t *p, const void *data,
apr_status_t (*cleanup)(void *));
/**
- * Run the specified cleanup function immediately and unregister it
+ * 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
* @param data The data to remove from cleanup
* @param cleanup The function to remove from cleanup
- * @deffunc apr_status_t apr_pool_cleanup_run(apr_pool_t *p, void *data, apr_status_t (*cleanup)(void *))
*/
APR_DECLARE(apr_status_t) apr_pool_cleanup_run(apr_pool_t *p, void *data,
apr_status_t (*cleanup)(void *));
@@ -375,14 +355,12 @@
/**
* Run all of the child_cleanups, so that any unnecessary files are
* closed because we are about to exec a new program
- * @deffunc void apr_pool_cleanup_for_exec(void)
*/
APR_DECLARE(void) apr_pool_cleanup_for_exec(void);
/**
* An empty cleanup function
* @param data The data to cleanup
- * @deffunc apr_status_t apr_pool_cleanup_null(void *data)
*/
APR_DECLARE_NONSTD(apr_status_t) apr_pool_cleanup_null(void *data);
@@ -420,10 +398,10 @@
/* used to guarantee to the apr_pool_t debugging code that the sub apr_pool_t
* will not be destroyed before the parent pool */
#ifndef APR_POOL_DEBUG
-#ifdef apr_pool_join
-#undef apr_pool_join
-#endif /* apr_pool_join */
-#define apr_pool_join(a,b)
+# ifdef apr_pool_join
+# undef apr_pool_join
+# endif /* apr_pool_join */
+# define apr_pool_join(a,b)
#endif /* APR_POOL_DEBUG */
#ifdef __cplusplus
1.90 +1 -1 apr/lib/apr_pools.c
Index: apr_pools.c
===================================================================
RCS file: /home/cvs/apr/lib/apr_pools.c,v
retrieving revision 1.89
retrieving revision 1.90
diff -u -r1.89 -r1.90
--- apr_pools.c 2001/02/25 20:39:33 1.89
+++ apr_pools.c 2001/03/11 23:24:56 1.90
@@ -592,7 +592,7 @@
}
APR_DECLARE(void) apr_pool_cleanup_kill(apr_pool_t *p, const void *data,
- apr_status_t (*cleanup) (void *))
+ apr_status_t (*cleanup) (void *))
{
struct cleanup *c;
struct cleanup **lastp;