forked from osmocom/wireshark
First batch of doxygen for wmem. Remove some things from README.wmem now that
they're in doxygen instead. svn path=/trunk/; revision=49583
This commit is contained in:
parent
2ab2ad7a42
commit
a9c35aa4b6
|
@ -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
|
||||
declared in wmem_user_cb.h. Every time the memory in a pool is freed, all
|
||||
registered cleanup functions are called first.
|
||||
|
||||
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
|
||||
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
|
||||
|
||||
|
|
|
@ -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 */
|
||||
|
|
|
@ -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 */
|
||||
|
|
|
@ -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 */
|
||||
|
|
|
@ -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 */
|
||||
|
|
|
@ -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 */
|
||||
|
|
|
@ -26,20 +26,53 @@
|
|||
#ifndef __WMEM_USER_CB_H__
|
||||
#define __WMEM_USER_CB_H__
|
||||
|
||||
#include <glib.h>
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif /* __cplusplus */
|
||||
|
||||
#include <glib.h>
|
||||
/** @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 */
|
||||
|
|
Loading…
Reference in New Issue