From: Evan Huus Date: Sun, 26 May 2013 02:40:40 +0000 (-0000) Subject: First batch of doxygen for wmem. Remove some things from README.wmem now that X-Git-Url: http://git.samba.org/?p=metze%2Fwireshark%2Fwip.git;a=commitdiff_plain;h=a9c35aa4b65dc566ffe845e9bc205e81ecc7979c First batch of doxygen for wmem. Remove some things from README.wmem now that they're in doxygen instead. svn path=/trunk/; revision=49583 --- diff --git a/doc/README.wmem b/doc/README.wmem index 9bdf4e4f7b..c2f10964e1 100644 --- a/doc/README.wmem +++ b/doc/README.wmem @@ -111,26 +111,10 @@ Sometimes (though hopefully rarely) it may be necessary to store data in a wmem pool that requires additional cleanup before it is freed. For example, perhaps you have a pointer to a file-handle that needs to be closed. In this case, you can register a callback with the wmem_register_cleanup_callback function -declared in wmem_user_cb.h. This function takes as parameters: - - the allocator - - boolean indicating whether or not the callback should be recurring (ie - happens once if FALSE, or every time if TRUE) - - the callback function (signature defined in wmem_user_cb.h) - - a void user_data pointer - -Every time the memory in a pool is freed, all registered cleanup functions are -called first, being passed: - - a pointer to the allocator - - a boolean indicating if this is just a free_all (FALSE) or if this was - triggered by destruction of the entire pool (TRUE) - mostly useful for - recurring callbacks - - whatever user_data was registered with that callback. - -Note that the user_data pointer is not freed when a callback is finished, you -have to do that yourself in the callback, or just allocate it in the -appropriate wmem pool. - -Also note that callback calling order is not defined, you cannot rely on a +declared in wmem_user_cb.h. Every time the memory in a pool is freed, all +registered cleanup functions are called first. + +Note that callback calling order is not defined, you cannot rely on a certain callback being called before or after another. WARNING: Manually freeing or moving memory (with wmem_free or wmem_realloc) @@ -152,22 +136,8 @@ pool to pick one. 3.1 Available Allocator Back-Ends Each available allocator type has a corresponding entry in the -wmem_allocator_type_t enumeration defined in wmem_core.h. - -The currently available allocators are: - - WMEM_ALLOCATOR_SIMPLE (wmem_allocator_simple.*) - A trivial allocator that g_allocs requested memory and tracks - allocations via a GHashTable. As simple as possible, intended more as - a demo than for practical usage. Also has the benefit of being friendly - to tools like valgrind. - - WMEM_ALLOCATOR_BLOCK (wmem_allocator_block.*) - A block allocator that grabs large chunks of memory at a time - (8 MB currently) and serves allocations out of those chunks. - Designed for efficiency, especially in the free_all operation. - - WMEM_ALLOCATOR_STRICT (wmem_allocator_strict.*) - An allocator that does its best to find invalid memory usage via - things like canaries and scrubbing freed memory. Valgrind is the - better choice on platforms that support it. +wmem_allocator_type_t enumeration defined in wmem_core.h. See the doxygen +comments in that header file for details on each type. 3.2 Creating a Pool diff --git a/epan/wmem/wmem_core.h b/epan/wmem/wmem_core.h index 238a57c89d..7e9862a08c 100644 --- a/epan/wmem/wmem_core.h +++ b/epan/wmem/wmem_core.h @@ -34,66 +34,164 @@ extern "C" { #endif /* __cplusplus */ -/* Allocator structure and typedef */ +/** @defgroup wmem Wireshark Memory Manager + * + * Wmem is a memory management framework for Wireshark that makes it simple to + * write dissectors (and other 'user-space' code) that doesn't leak memory. The + * core module provides basic functions like malloc, realloc and free, but + * many other functions are available (see the "Modules" list at the top of + * the generated doxygen HTML). + * + * @{ + */ + struct _wmem_allocator_t; +/** A public opaque type representing one wmem allocation pool. */ typedef struct _wmem_allocator_t wmem_allocator_t; -/* Different types of allocators */ +/** An enumeration of the different types of available allocators. */ typedef enum _wmem_allocator_type_t { - WMEM_ALLOCATOR_SIMPLE, - WMEM_ALLOCATOR_BLOCK, - WMEM_ALLOCATOR_STRICT + WMEM_ALLOCATOR_SIMPLE, /**< A trivial allocator that g_allocs requested + memory and tracks allocations via a GHashTable. As simple as + possible, intended more as a demo than for practical usage. Also + has the benefit of being friendly to tools like valgrind. */ + WMEM_ALLOCATOR_BLOCK, /**< A block allocator that grabs large chunks of + memory at a time (8 MB currently) and serves allocations out of + those chunks. Designed for efficiency, especially in the + free_all operation. */ + WMEM_ALLOCATOR_STRICT /**< An allocator that does its best to find invalid + memory usage via things like canaries and scrubbing freed + memory. Valgrind is the better choice on platforms that support + it. */ } wmem_allocator_type_t; +/** Allocate the requested amount of memory in the given pool. + * + * @param allocator The allocator object to use to allocate the memory. + * @param size The amount of memory to allocate. + * @return A void pointer to the newly allocated memory. + */ WS_DLL_PUBLIC void * wmem_alloc(wmem_allocator_t *allocator, const size_t size) G_GNUC_MALLOC; +/** Allocate memory sufficient to hold one object of the given type. + * + * @param allocator The allocator object to use to allocate the memory. + * @param type The type that the newly allocated memory will hold. + * @return A void pointer to the newly allocated memory. + */ #define wmem_new(allocator, type) \ ((type*)wmem_alloc((allocator), sizeof(type))) +/** Allocate the requested amount of memory in the given pool. Initializes the + * allocated memory with zeroes. + * + * @param allocator The allocator object to use to allocate the memory. + * @param size The amount of memory to allocate. + * @return A void pointer to the newly allocated and zeroed memory. + */ WS_DLL_PUBLIC void * wmem_alloc0(wmem_allocator_t *allocator, const size_t size) G_GNUC_MALLOC; +/** Allocate memory sufficient to hold one object of the given type. + * Initializes the allocated memory with zeroes. + * + * @param allocator The allocator object to use to allocate the memory. + * @param type The type that the newly allocated memory will hold. + * @return A void pointer to the newly allocated and zeroed memory. + */ #define wmem_new0(allocator, type) \ ((type*)wmem_alloc0((allocator), sizeof(type))) +/** Returns the allocated memory to the allocator. This function should only + * be called directly by allocators when the allocated block is sufficiently + * large that the reduced memory usage is worth the cost of the extra function + * call. It's usually easier to just let it get cleaned up when wmem_free_all() + * is called. + * + * @param allocator The allocator object used to originally allocate the memory. + * @param ptr The pointer to the memory block to free. After this function + * returns it no longer points to valid memory. + */ WS_DLL_PUBLIC void wmem_free(wmem_allocator_t *allocator, void *ptr); +/** Resizes a block of memory, potentially moving it if resizing it in place + * is not possible. + * + * @param allocator The allocator object used to originally allocate the memory. + * @param ptr The pointer to the memory block to resize. + * @param size The new size for the memory block. + * @return The new location of the memory block. If this is different from ptr + * then ptr no longer points to valid memory. + */ WS_DLL_PUBLIC void * wmem_realloc(wmem_allocator_t *allocator, void *ptr, const size_t size) G_GNUC_MALLOC; +/** Frees all the memory allocated in a pool. Depending on the allocator + * implementation used this can be significantly cheaper than calling + * wmem_free() on all the individual blocks. It also doesn't require you to have + * external pointers to those blocks. + * + * @param allocator The allocator to free the memory from. + */ WS_DLL_PUBLIC void wmem_free_all(wmem_allocator_t *allocator); +/** Triggers a garbage-collection in the allocator. This does not free any + * memory, but it can return unused blocks to the operating system or perform + * other optimizations. + * + * @param allocator The allocator in which to trigger the garbage collection. + */ WS_DLL_PUBLIC void wmem_gc(wmem_allocator_t *allocator); +/** Destroy the given allocator, freeing all memory allocated in it. Once this + * function has been called, no memory allocated with the allocator is valid. + * + * @param allocator The allocator to destroy. + */ WS_DLL_PUBLIC void wmem_destroy_allocator(wmem_allocator_t *allocator); +/** Create a new allocator of the given type. The type may be overridden by the + * WIRESHARK_DEBUG_WMEM_OVERRIDE environment variable. + * + * @param type The type of allocator to create. + * @return The new allocator. + */ WS_DLL_PUBLIC wmem_allocator_t * wmem_allocator_new(const wmem_allocator_type_t type); +/** Initialize the wmem subsystem. This must be called before any other wmem + * function, usually at the very beginning of your program. + */ WS_DLL_LOCAL void wmem_init(void); +/** Teardown the wmem subsystem. This must be called after all other wmem + * functions, usually at the very end of your program. This function will not + * destroy outstanding allocators, you must do that yourself. + */ WS_DLL_LOCAL void wmem_cleanup(void); +/** @} */ + #ifdef __cplusplus } #endif /* __cplusplus */ diff --git a/epan/wmem/wmem_slist.h b/epan/wmem/wmem_slist.h index 3e9f1e0bfc..cd06e64d08 100644 --- a/epan/wmem/wmem_slist.h +++ b/epan/wmem/wmem_slist.h @@ -35,6 +35,15 @@ extern "C" { #endif /* __cplusplus */ +/** @addtogroup wmem + * @{ + * @defgroup wmem-slist Singly-Linked List + * + * A singly-linked list implementation on top of wmem. + * + * @{ + */ + struct _wmem_slist_t; struct _wmem_slist_frame_t; @@ -74,6 +83,9 @@ wmem_slist_t * wmem_slist_new(wmem_allocator_t *allocator) G_GNUC_MALLOC; +/** @} + * @} */ + #ifdef __cplusplus } #endif /* __cplusplus */ diff --git a/epan/wmem/wmem_stack.h b/epan/wmem/wmem_stack.h index 9a2a569de2..a85c47a3a5 100644 --- a/epan/wmem/wmem_stack.h +++ b/epan/wmem/wmem_stack.h @@ -36,6 +36,15 @@ extern "C" { #endif /* __cplusplus */ +/** @addtogroup wmem + * @{ + * @defgroup wmem-stack Stack + * + * A stack implementation on top of wmem. + * + * @{ + */ + /* Wmem stack is implemented as a simple wrapper over Wmem slist */ typedef wmem_slist_t wmem_stack_t; @@ -55,6 +64,9 @@ wmem_stack_push(wmem_stack_t *stack, void *data); #define wmem_stack_new(ALLOCATOR) wmem_slist_new(ALLOCATOR) +/** @} + * @} */ + #ifdef __cplusplus } #endif /* __cplusplus */ diff --git a/epan/wmem/wmem_strbuf.h b/epan/wmem/wmem_strbuf.h index 3e24a36e75..4b0f498c99 100644 --- a/epan/wmem/wmem_strbuf.h +++ b/epan/wmem/wmem_strbuf.h @@ -35,6 +35,15 @@ extern "C" { #endif /* __cplusplus */ +/** @addtogroup wmem + * @{ + * @defgroup wmem-strbuf String Buffer + * + * A string object implementation on top of wmem. + * + * @{ + */ + struct _wmem_strbuf_t; typedef struct _wmem_strbuf_t wmem_strbuf_t; @@ -79,6 +88,9 @@ WS_DLL_PUBLIC gsize wmem_strbuf_get_len(wmem_strbuf_t *strbuf); +/** @} + * @} */ + #ifdef __cplusplus } #endif /* __cplusplus */ diff --git a/epan/wmem/wmem_strutl.h b/epan/wmem/wmem_strutl.h index cf412d6bf7..14f2702b77 100644 --- a/epan/wmem/wmem_strutl.h +++ b/epan/wmem/wmem_strutl.h @@ -34,6 +34,15 @@ extern "C" { #endif /* __cplusplus */ +/** @addtogroup wmem + * @{ + * @defgroup wmem-strutl String Utilities + * + * A collection of utility function for operating on C strings with wmem. + * + * @{ + */ + WS_DLL_PUBLIC gchar * wmem_strdup(wmem_allocator_t *allocator, const gchar *src) @@ -54,6 +63,9 @@ gchar * wmem_strdup_vprintf(wmem_allocator_t *allocator, const gchar *fmt, va_list ap) G_GNUC_MALLOC; +/** @} + * @} */ + #ifdef __cplusplus } #endif /* __cplusplus */ diff --git a/epan/wmem/wmem_user_cb.h b/epan/wmem/wmem_user_cb.h index 5a2ddbee71..929c8dc030 100644 --- a/epan/wmem/wmem_user_cb.h +++ b/epan/wmem/wmem_user_cb.h @@ -26,20 +26,53 @@ #ifndef __WMEM_USER_CB_H__ #define __WMEM_USER_CB_H__ +#include + #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ -#include +/** @addtogroup wmem + * @{ + * @defgroup wmem-user-cb User Callbacks + * + * User callbacks. + * + * @{ + */ -/* User callback type for registering cleanup routines */ +/** Function signature for registered user callbacks. + * + * @param allocator The allocator that triggered this callback. + * @param final Whether this is was triggered due to the allocator being + * destroyed (TRUE) or simply a call to wmem_free_all() (FALSE). + * @param user_data Whatever user_data was originally passed to the call to + * wmem_register_cleanup_callback(). + */ typedef void (*wmem_user_cb_t) (wmem_allocator_t *, gboolean, void *); +/** Register a callback function with the given allocator pool. + * + * @param allocator The allocator with which to register the callback. + * @param recurring If this is FALSE then the callback is called exactly once. + * If this is TRUE then the callback is called every time + * wmem_free_all() is called on the allocator, and one last + * time when wmem_destroy_allocator() is called on it. + * @param callback The function to be called as the callback. + * @param user_data An arbitrary data pointer that is passed to the callback as + * a way to specify extra parameters or store extra data. Note + * that this pointer is not freed when a callback is finished, + * you have to do that yourself in the callback, or just + * allocate it in the appropriate wmem pool. + */ WS_DLL_PUBLIC void wmem_register_cleanup_callback(wmem_allocator_t *allocator, gboolean recurring, wmem_user_cb_t callback, void *user_data); +/** @} + * @} */ + #ifdef __cplusplus } #endif /* __cplusplus */