Wireshark Memory Manager

Modules
	Array
	Interval Tree
	Doubly-Linked List
	Hash Map
	String Utilities
	Hash Multimap
	Queue
	Stack
	String Buffer
	Red/Black Tree
	User Callbacks

Macros
#define	wmem_new(allocator, type)    ((type*)wmem_alloc((allocator), sizeof(type)))
#define	wmem_safe_mult_type_size(type, num)    ((((num) <= 0) || ((size_t)sizeof(type) > (G_MAXSSIZE / (size_t)(num)))) ? 0 : (sizeof(type) * (num)))
#define	wmem_alloc_array(allocator, type, num)    ((type*)wmem_alloc((allocator), wmem_safe_mult_type_size(type, (num))))
#define	wmem_new0(allocator, type)    ((type*)wmem_alloc0((allocator), sizeof(type)))
#define	wmem_alloc0_array(allocator, type, num)    ((type*)wmem_alloc0((allocator), wmem_safe_mult_type_size(type, (num))))

Typedefs
typedef struct _wmem_allocator_t	wmem_allocator_t
typedef enum _wmem_allocator_type_t	wmem_allocator_type_t

Enumerations
enum	_wmem_allocator_type_t { WMEM_ALLOCATOR_SIMPLE , WMEM_ALLOCATOR_BLOCK , WMEM_ALLOCATOR_STRICT , WMEM_ALLOCATOR_BLOCK_FAST }

Functions
WS_DLL_PUBLIC void *	wmem_alloc (wmem_allocator_t *allocator, const size_t size) G_GNUC_MALLOC
WS_DLL_PUBLIC void *	wmem_alloc0 (wmem_allocator_t *allocator, const size_t size) G_GNUC_MALLOC
WS_DLL_PUBLIC void	wmem_free (wmem_allocator_t *allocator, void *ptr)
WS_DLL_PUBLIC void *	wmem_realloc (wmem_allocator_t *allocator, void *ptr, const size_t size) G_GNUC_MALLOC
WS_DLL_PUBLIC void	wmem_free_all (wmem_allocator_t *allocator)
WS_DLL_PUBLIC void	wmem_gc (wmem_allocator_t *allocator)
WS_DLL_PUBLIC void	wmem_destroy_allocator (wmem_allocator_t *allocator)
WS_DLL_PUBLIC wmem_allocator_t *	wmem_allocator_new (const wmem_allocator_type_t type)
WS_DLL_PUBLIC void	wmem_init (void)
WS_DLL_PUBLIC void	wmem_cleanup (void)
WS_DLL_PUBLIC void	wmem_enter_scope (wmem_allocator_t *allocator)
WS_DLL_PUBLIC void	wmem_leave_scope (wmem_allocator_t *allocator)
WS_DLL_PUBLIC bool	wmem_in_scope (wmem_allocator_t *allocator)

Detailed Description

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).

Any wmem functions which allocate memory are guaranteed to either succeed or abort the program. However, they can still legally return NULL when the amount of requested memory is zero.

Macro Definition Documentation

wmem_alloc0_array

#define wmem_alloc0_array	(		allocator,
			type,
			num
	)		((type*)wmem_alloc0((allocator), wmem_safe_mult_type_size(type, (num))))

Allocate memory sufficient to hold n objects of the given type. Initializes the allocated memory with zeroes.

Parameters

allocator	The allocator object to use to allocate the memory.
type	The type that the newly allocated memory will hold.
num	The number of objects that the newly allocated memory will hold.

Returns

A void pointer to the newly allocated and zeroed memory.

wmem_alloc_array

#define wmem_alloc_array	(		allocator,
			type,
			num
	)		((type*)wmem_alloc((allocator), wmem_safe_mult_type_size(type, (num))))

Allocate memory sufficient to hold n objects of the given type.

Parameters

allocator	The allocator object to use to allocate the memory.
type	The type that the newly allocated memory will hold.
num	The number of objects that the newly allocated memory will hold.

Returns

A void pointer to the newly allocated memory.

wmem_new

#define wmem_new	(		allocator,
			type
	)		((type*)wmem_alloc((allocator), sizeof(type)))

Allocate memory sufficient to hold one object of the given type.

Parameters

allocator	The allocator object to use to allocate the memory.
type	The type that the newly allocated memory will hold.

Returns

A void pointer to the newly allocated memory.

wmem_new0

#define wmem_new0	(		allocator,
			type
	)		((type*)wmem_alloc0((allocator), sizeof(type)))

Allocate memory sufficient to hold one object of the given type. Initializes the allocated memory with zeroes.

Parameters

allocator	The allocator object to use to allocate the memory.
type	The type that the newly allocated memory will hold.

Returns

A void pointer to the newly allocated and zeroed memory.

Typedef Documentation

wmem_allocator_t

typedef struct _wmem_allocator_t wmem_allocator_t

A public opaque type representing one wmem allocation pool.

wmem_allocator_type_t

typedef enum _wmem_allocator_type_t wmem_allocator_type_t

An enumeration of the different types of available allocators.

Enumeration Type Documentation

_wmem_allocator_type_t

enum _wmem_allocator_type_t

An enumeration of the different types of available allocators.

Enumerator
WMEM_ALLOCATOR_SIMPLE	A trivial allocator that mallocs requested memory and tracks allocations via a hash table. 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_BLOCK_FAST	A block allocator like WMEM_ALLOCATOR_BLOCK but even faster by tracking absolutely minimal metadata and making 'free' a no-op. Useful only for very short-lived scopes where there's no reason to free individual allocations because the next free_all is always just around the corner.

Function Documentation

wmem_alloc()

WS_DLL_PUBLIC void* wmem_alloc	(	wmem_allocator_t *	allocator,
		const size_t	size
	)

Allocate the requested amount of memory in the given pool.

Parameters

allocator	The allocator object to use to allocate the memory.
size	The amount of memory to allocate.

Returns

A void pointer to the newly allocated memory.

wmem_alloc0()

WS_DLL_PUBLIC void* wmem_alloc0	(	wmem_allocator_t *	allocator,
		const size_t	size
	)

Allocate the requested amount of memory in the given pool. Initializes the allocated memory with zeroes.

Parameters

allocator	The allocator object to use to allocate the memory.
size	The amount of memory to allocate.

Returns

A void pointer to the newly allocated and zeroed memory.

wmem_allocator_new()

WS_DLL_PUBLIC wmem_allocator_t* wmem_allocator_new

(

const wmem_allocator_type_t

type

)

Create a new allocator of the given type. The type may be overridden by the WIRESHARK_DEBUG_WMEM_OVERRIDE environment variable.

Parameters

type	The type of allocator to create.

Returns

The new allocator.

wmem_cleanup()

WS_DLL_PUBLIC void wmem_cleanup

(

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.

wmem_destroy_allocator()

WS_DLL_PUBLIC void wmem_destroy_allocator

(

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.

Parameters

allocator

The allocator to destroy.

wmem_free()

WS_DLL_PUBLIC void wmem_free	(	wmem_allocator_t *	allocator,
		void *	ptr
	)

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.

Parameters

allocator	The allocator object used to originally allocate the memory.
ptr	The pointer to the memory block to free. After this function returns it no longer points to valid memory.

wmem_free_all()

WS_DLL_PUBLIC void wmem_free_all

(

wmem_allocator_t *

allocator

)

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.

Parameters

allocator

The allocator to free the memory from.

wmem_gc()

WS_DLL_PUBLIC void wmem_gc

(

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.

Parameters

allocator

The allocator in which to trigger the garbage collection.

wmem_init()

WS_DLL_PUBLIC void wmem_init

(

void

)

Initialize the wmem subsystem. This must be called before any other wmem function, usually at the very beginning of your program.

wmem_realloc()

WS_DLL_PUBLIC void* wmem_realloc	(	wmem_allocator_t *	allocator,
		void *	ptr,
		const size_t	size
	)

Resizes a block of memory, potentially moving it if resizing it in place is not possible.

Parameters

allocator	The allocator object used to originally allocate the memory.
ptr	The pointer to the memory block to resize.
size	The new size for the memory block.

Returns

The new location of the memory block. If this is different from ptr then ptr no longer points to valid memory.