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
|
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
|
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
|
can register a callback with the wmem_register_cleanup_callback function
|
||||||
declared in wmem_user_cb.h. This function takes as parameters:
|
declared in wmem_user_cb.h. Every time the memory in a pool is freed, all
|
||||||
- the allocator
|
registered cleanup functions are called first.
|
||||||
- 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
|
Note that callback calling order is not defined, you cannot rely on a
|
||||||
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
|
|
||||||
certain callback being called before or after another.
|
certain callback being called before or after another.
|
||||||
|
|
||||||
WARNING: Manually freeing or moving memory (with wmem_free or wmem_realloc)
|
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
|
3.1 Available Allocator Back-Ends
|
||||||
|
|
||||||
Each available allocator type has a corresponding entry in the
|
Each available allocator type has a corresponding entry in the
|
||||||
wmem_allocator_type_t enumeration defined in wmem_core.h.
|
wmem_allocator_type_t enumeration defined in wmem_core.h. See the doxygen
|
||||||
|
comments in that header file for details on each type.
|
||||||
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.
|
|
||||||
|
|
||||||
3.2 Creating a Pool
|
3.2 Creating a Pool
|
||||||
|
|
||||||
|
|
|
@ -34,66 +34,164 @@
|
||||||
extern "C" {
|
extern "C" {
|
||||||
#endif /* __cplusplus */
|
#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;
|
struct _wmem_allocator_t;
|
||||||
|
/** A public opaque type representing one wmem allocation pool. */
|
||||||
typedef struct _wmem_allocator_t wmem_allocator_t;
|
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 {
|
typedef enum _wmem_allocator_type_t {
|
||||||
WMEM_ALLOCATOR_SIMPLE,
|
WMEM_ALLOCATOR_SIMPLE, /**< A trivial allocator that g_allocs requested
|
||||||
WMEM_ALLOCATOR_BLOCK,
|
memory and tracks allocations via a GHashTable. As simple as
|
||||||
WMEM_ALLOCATOR_STRICT
|
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;
|
} 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
|
WS_DLL_PUBLIC
|
||||||
void *
|
void *
|
||||||
wmem_alloc(wmem_allocator_t *allocator, const size_t size)
|
wmem_alloc(wmem_allocator_t *allocator, const size_t size)
|
||||||
G_GNUC_MALLOC;
|
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) \
|
#define wmem_new(allocator, type) \
|
||||||
((type*)wmem_alloc((allocator), sizeof(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
|
WS_DLL_PUBLIC
|
||||||
void *
|
void *
|
||||||
wmem_alloc0(wmem_allocator_t *allocator, const size_t size)
|
wmem_alloc0(wmem_allocator_t *allocator, const size_t size)
|
||||||
G_GNUC_MALLOC;
|
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) \
|
#define wmem_new0(allocator, type) \
|
||||||
((type*)wmem_alloc0((allocator), sizeof(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
|
WS_DLL_PUBLIC
|
||||||
void
|
void
|
||||||
wmem_free(wmem_allocator_t *allocator, void *ptr);
|
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
|
WS_DLL_PUBLIC
|
||||||
void *
|
void *
|
||||||
wmem_realloc(wmem_allocator_t *allocator, void *ptr, const size_t size)
|
wmem_realloc(wmem_allocator_t *allocator, void *ptr, const size_t size)
|
||||||
G_GNUC_MALLOC;
|
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
|
WS_DLL_PUBLIC
|
||||||
void
|
void
|
||||||
wmem_free_all(wmem_allocator_t *allocator);
|
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
|
WS_DLL_PUBLIC
|
||||||
void
|
void
|
||||||
wmem_gc(wmem_allocator_t *allocator);
|
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
|
WS_DLL_PUBLIC
|
||||||
void
|
void
|
||||||
wmem_destroy_allocator(wmem_allocator_t *allocator);
|
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
|
WS_DLL_PUBLIC
|
||||||
wmem_allocator_t *
|
wmem_allocator_t *
|
||||||
wmem_allocator_new(const wmem_allocator_type_t type);
|
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
|
WS_DLL_LOCAL
|
||||||
void
|
void
|
||||||
wmem_init(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
|
WS_DLL_LOCAL
|
||||||
void
|
void
|
||||||
wmem_cleanup(void);
|
wmem_cleanup(void);
|
||||||
|
|
||||||
|
/** @} */
|
||||||
|
|
||||||
#ifdef __cplusplus
|
#ifdef __cplusplus
|
||||||
}
|
}
|
||||||
#endif /* __cplusplus */
|
#endif /* __cplusplus */
|
||||||
|
|
|
@ -35,6 +35,15 @@
|
||||||
extern "C" {
|
extern "C" {
|
||||||
#endif /* __cplusplus */
|
#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_t;
|
||||||
struct _wmem_slist_frame_t;
|
struct _wmem_slist_frame_t;
|
||||||
|
|
||||||
|
@ -74,6 +83,9 @@ wmem_slist_t *
|
||||||
wmem_slist_new(wmem_allocator_t *allocator)
|
wmem_slist_new(wmem_allocator_t *allocator)
|
||||||
G_GNUC_MALLOC;
|
G_GNUC_MALLOC;
|
||||||
|
|
||||||
|
/** @}
|
||||||
|
* @} */
|
||||||
|
|
||||||
#ifdef __cplusplus
|
#ifdef __cplusplus
|
||||||
}
|
}
|
||||||
#endif /* __cplusplus */
|
#endif /* __cplusplus */
|
||||||
|
|
|
@ -36,6 +36,15 @@
|
||||||
extern "C" {
|
extern "C" {
|
||||||
#endif /* __cplusplus */
|
#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 */
|
/* Wmem stack is implemented as a simple wrapper over Wmem slist */
|
||||||
typedef wmem_slist_t wmem_stack_t;
|
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)
|
#define wmem_stack_new(ALLOCATOR) wmem_slist_new(ALLOCATOR)
|
||||||
|
|
||||||
|
/** @}
|
||||||
|
* @} */
|
||||||
|
|
||||||
#ifdef __cplusplus
|
#ifdef __cplusplus
|
||||||
}
|
}
|
||||||
#endif /* __cplusplus */
|
#endif /* __cplusplus */
|
||||||
|
|
|
@ -35,6 +35,15 @@
|
||||||
extern "C" {
|
extern "C" {
|
||||||
#endif /* __cplusplus */
|
#endif /* __cplusplus */
|
||||||
|
|
||||||
|
/** @addtogroup wmem
|
||||||
|
* @{
|
||||||
|
* @defgroup wmem-strbuf String Buffer
|
||||||
|
*
|
||||||
|
* A string object implementation on top of wmem.
|
||||||
|
*
|
||||||
|
* @{
|
||||||
|
*/
|
||||||
|
|
||||||
struct _wmem_strbuf_t;
|
struct _wmem_strbuf_t;
|
||||||
|
|
||||||
typedef struct _wmem_strbuf_t wmem_strbuf_t;
|
typedef struct _wmem_strbuf_t wmem_strbuf_t;
|
||||||
|
@ -79,6 +88,9 @@ WS_DLL_PUBLIC
|
||||||
gsize
|
gsize
|
||||||
wmem_strbuf_get_len(wmem_strbuf_t *strbuf);
|
wmem_strbuf_get_len(wmem_strbuf_t *strbuf);
|
||||||
|
|
||||||
|
/** @}
|
||||||
|
* @} */
|
||||||
|
|
||||||
#ifdef __cplusplus
|
#ifdef __cplusplus
|
||||||
}
|
}
|
||||||
#endif /* __cplusplus */
|
#endif /* __cplusplus */
|
||||||
|
|
|
@ -34,6 +34,15 @@
|
||||||
extern "C" {
|
extern "C" {
|
||||||
#endif /* __cplusplus */
|
#endif /* __cplusplus */
|
||||||
|
|
||||||
|
/** @addtogroup wmem
|
||||||
|
* @{
|
||||||
|
* @defgroup wmem-strutl String Utilities
|
||||||
|
*
|
||||||
|
* A collection of utility function for operating on C strings with wmem.
|
||||||
|
*
|
||||||
|
* @{
|
||||||
|
*/
|
||||||
|
|
||||||
WS_DLL_PUBLIC
|
WS_DLL_PUBLIC
|
||||||
gchar *
|
gchar *
|
||||||
wmem_strdup(wmem_allocator_t *allocator, const gchar *src)
|
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)
|
wmem_strdup_vprintf(wmem_allocator_t *allocator, const gchar *fmt, va_list ap)
|
||||||
G_GNUC_MALLOC;
|
G_GNUC_MALLOC;
|
||||||
|
|
||||||
|
/** @}
|
||||||
|
* @} */
|
||||||
|
|
||||||
#ifdef __cplusplus
|
#ifdef __cplusplus
|
||||||
}
|
}
|
||||||
#endif /* __cplusplus */
|
#endif /* __cplusplus */
|
||||||
|
|
|
@ -26,20 +26,53 @@
|
||||||
#ifndef __WMEM_USER_CB_H__
|
#ifndef __WMEM_USER_CB_H__
|
||||||
#define __WMEM_USER_CB_H__
|
#define __WMEM_USER_CB_H__
|
||||||
|
|
||||||
|
#include <glib.h>
|
||||||
|
|
||||||
#ifdef __cplusplus
|
#ifdef __cplusplus
|
||||||
extern "C" {
|
extern "C" {
|
||||||
#endif /* __cplusplus */
|
#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 *);
|
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
|
WS_DLL_PUBLIC
|
||||||
void
|
void
|
||||||
wmem_register_cleanup_callback(wmem_allocator_t *allocator, gboolean recurring,
|
wmem_register_cleanup_callback(wmem_allocator_t *allocator, gboolean recurring,
|
||||||
wmem_user_cb_t callback, void *user_data);
|
wmem_user_cb_t callback, void *user_data);
|
||||||
|
|
||||||
|
/** @}
|
||||||
|
* @} */
|
||||||
|
|
||||||
#ifdef __cplusplus
|
#ifdef __cplusplus
|
||||||
}
|
}
|
||||||
#endif /* __cplusplus */
|
#endif /* __cplusplus */
|
||||||
|
|
Loading…
Reference in New Issue