wsutil/wmem/wmem_core.h

   1 /** @file
   2  * Definitions for the Wireshark Memory Manager Core
   3  * Copyright 2012, Evan Huus <eapache@gmail.com>
   4  *
   5  * Wireshark - Network traffic analyzer
   6  * By Gerald Combs <gerald@wireshark.org>
   7  * Copyright 1998 Gerald Combs
   8  *
   9  * SPDX-License-Identifier: GPL-2.0-or-later
  10  */
  11
  12 #ifndef __WMEM_CORE_H__
  13 #define __WMEM_CORE_H__
  14
  15 #include <stdint.h>
  16 #include <stdbool.h>
  17 #include <string.h>
  18 #include <glib.h>
  19 #include <ws_symbol_export.h>
  20 #include <ws_attributes.h>
  21 #include <ws_posix_compat.h>
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif /* __cplusplus */
  26
  27 /** @defgroup wmem Wireshark Memory Manager
  28  *
  29  * Wmem is a memory management framework for Wireshark that makes it simple to
  30  * write dissectors (and other 'user-space' code) that doesn't leak memory. The
  31  * core module provides basic functions like malloc, realloc and free, but
  32  * many other functions are available (see the "Modules" list at the top of
  33  * the generated doxygen HTML).
  34  *
  35  * Any wmem functions which allocate memory are guaranteed to either succeed or
  36  * abort the program. However, they *can* still legally return NULL when the
  37  * amount of requested memory is zero.
  38  *
  39  * @{
  40  */
  41
  42 struct _wmem_allocator_t;
  43 /** A public opaque type representing one wmem allocation pool. */
  44 typedef struct _wmem_allocator_t wmem_allocator_t;
  45
  46 /** An enumeration of the different types of available allocators. */
  47 typedef enum _wmem_allocator_type_t {
  48     WMEM_ALLOCATOR_SIMPLE, /**< A trivial allocator that mallocs requested
  49                 memory and tracks allocations via a hash table. As simple as
  50                 possible, intended more as a demo than for practical usage. Also
  51                 has the benefit of being friendly to tools like valgrind. */
  52     WMEM_ALLOCATOR_BLOCK, /**< A block allocator that grabs large chunks of
  53                 memory at a time (8 MB currently) and serves allocations out of
  54                 those chunks. Designed for efficiency, especially in the
  55                 free_all operation. */
  56     WMEM_ALLOCATOR_STRICT, /**< An allocator that does its best to find invalid
  57                 memory usage via things like canaries and scrubbing freed
  58                 memory. Valgrind is the better choice on platforms that support
  59                 it. */
  60     WMEM_ALLOCATOR_BLOCK_FAST /**< A block allocator like WMEM_ALLOCATOR_BLOCK
  61                 but even faster by tracking absolutely minimal metadata and
  62                 making 'free' a no-op. Useful only for very short-lived scopes
  63                 where there's no reason to free individual allocations because
  64                 the next free_all is always just around the corner. */
  65 } wmem_allocator_type_t;
  66
  67 /** Allocate the requested amount of memory in the given pool.
  68  *
  69  * @param allocator The allocator object to use to allocate the memory.
  70  * @param size The amount of memory to allocate.
  71  * @return A void pointer to the newly allocated memory.
  72  */
  73 WS_DLL_PUBLIC
  74 void *
  75 wmem_alloc(wmem_allocator_t *allocator, const size_t size)
  76 G_GNUC_MALLOC
  77 G_GNUC_ALLOC_SIZE(2);
  78
  79 /** Allocate memory sufficient to hold one object of the given type.
  80  *
  81  * @param allocator The allocator object to use to allocate the memory.
  82  * @param type The type that the newly allocated memory will hold.
  83  * @return A void pointer to the newly allocated memory.
  84  */
  85 #define wmem_new(allocator, type) \
  86     ((type*)wmem_alloc((allocator), sizeof(type)))
  87
  88 /*
  89  * Overflow-safe multiplication of the size of a type by a number of
  90  * items of that type, returning 0 if the result would overflow (or
  91  * if the number of elements is negative), and the product otherwise.
  92  */
  93 #define wmem_safe_mult_type_size(type, num) \
  94     ((((num) <= 0) || ((size_t)sizeof(type) > (G_MAXSSIZE / (size_t)(num)))) ? 0 : (sizeof(type) * (num)))
  95
  96 /** Allocate memory sufficient to hold n objects of the given type.
  97  *
  98  * @param allocator The allocator object to use to allocate the memory.
  99  * @param type The type that the newly allocated memory will hold.
 100  * @param num  The number of objects that the newly allocated memory will hold.
 101  * @return A void pointer to the newly allocated memory.
 102  */
 103 #define wmem_alloc_array(allocator, type, num) \
 104     ((type*)wmem_alloc((allocator), wmem_safe_mult_type_size(type, (num))))
 105
 106 /** Allocate the requested amount of memory in the given pool. Initializes the
 107  * allocated memory with zeroes.
 108  *
 109  * @param allocator The allocator object to use to allocate the memory.
 110  * @param size The amount of memory to allocate.
 111  * @return A void pointer to the newly allocated and zeroed memory.
 112  */
 113 WS_DLL_PUBLIC
 114 void *
 115 wmem_alloc0(wmem_allocator_t *allocator, const size_t size)
 116 G_GNUC_MALLOC
 117 G_GNUC_ALLOC_SIZE(2);
 118
 119 /** Allocate memory sufficient to hold one object of the given type.
 120  * Initializes the allocated memory with zeroes.
 121  *
 122  * @param allocator The allocator object to use to allocate the memory.
 123  * @param type The type that the newly allocated memory will hold.
 124  * @return A void pointer to the newly allocated and zeroed memory.
 125  */
 126 #define wmem_new0(allocator, type) \
 127     ((type*)wmem_alloc0((allocator), sizeof(type)))
 128
 129 /** Allocate memory sufficient to hold n objects of the given type.
 130  * Initializes the allocated memory with zeroes.
 131  *
 132  * @param allocator The allocator object to use to allocate the memory.
 133  * @param type The type that the newly allocated memory will hold.
 134  * @param num  The number of objects that the newly allocated memory will hold.
 135  * @return A void pointer to the newly allocated and zeroed memory.
 136  */
 137 #define wmem_alloc0_array(allocator, type, num) \
 138     ((type*)wmem_alloc0((allocator), wmem_safe_mult_type_size(type, (num))))
 139
 140 /** Returns the allocated memory to the allocator. This function should only
 141  * be called directly by allocators when the allocated block is sufficiently
 142  * large that the reduced memory usage is worth the cost of the extra function
 143  * call. It's usually easier to just let it get cleaned up when wmem_free_all()
 144  * is called.
 145  *
 146  * @param allocator The allocator object used to originally allocate the memory.
 147  * @param ptr The pointer to the memory block to free. After this function
 148  * returns it no longer points to valid memory.
 149  */
 150 WS_DLL_PUBLIC
 151 void
 152 wmem_free(wmem_allocator_t *allocator, void *ptr);
 153
 154 /** Resizes a block of memory, potentially moving it if resizing it in place
 155  * is not possible.
 156  *
 157  * @param allocator The allocator object used to originally allocate the memory.
 158  * @param ptr The pointer to the memory block to resize.
 159  * @param size The new size for the memory block.
 160  * @return The new location of the memory block. If this is different from ptr
 161  * then ptr no longer points to valid memory.
 162  */
 163 WS_DLL_PUBLIC
 164 void *
 165 wmem_realloc(wmem_allocator_t *allocator, void *ptr, const size_t size)
 166 G_GNUC_ALLOC_SIZE(3);
 167
 168 /** Frees all the memory allocated in a pool. Depending on the allocator
 169  * implementation used this can be significantly cheaper than calling
 170  * wmem_free() on all the individual blocks. It also doesn't require you to have
 171  * external pointers to those blocks.
 172  *
 173  * @param allocator The allocator to free the memory from.
 174  */
 175 WS_DLL_PUBLIC
 176 void
 177 wmem_free_all(wmem_allocator_t *allocator);
 178
 179 /** Triggers a garbage-collection in the allocator. This does not free any
 180  * memory, but it can return unused blocks to the operating system or perform
 181  * other optimizations.
 182  *
 183  * @param allocator The allocator in which to trigger the garbage collection.
 184  */
 185 WS_DLL_PUBLIC
 186 void
 187 wmem_gc(wmem_allocator_t *allocator);
 188
 189 /** Destroy the given allocator, freeing all memory allocated in it. Once this
 190  * function has been called, no memory allocated with the allocator is valid.
 191  *
 192  * @param allocator The allocator to destroy.
 193  */
 194 WS_DLL_PUBLIC
 195 void
 196 wmem_destroy_allocator(wmem_allocator_t *allocator);
 197
 198 /** Create a new allocator of the given type. The type may be overridden by the
 199  * WIRESHARK_DEBUG_WMEM_OVERRIDE environment variable.
 200  *
 201  * @param type The type of allocator to create.
 202  * @return The new allocator.
 203  */
 204 WS_DLL_PUBLIC
 205 wmem_allocator_t *
 206 wmem_allocator_new(const wmem_allocator_type_t type);
 207
 208 /** Initialize the wmem subsystem. This must be called before any other wmem
 209  * function, usually at the very beginning of your program.
 210  */
 211 WS_DLL_PUBLIC
 212 void
 213 wmem_init(void);
 214
 215 /** Teardown the wmem subsystem. This must be called after all other wmem
 216  * functions, usually at the very end of your program. This function will not
 217  * destroy outstanding allocators, you must do that yourself.
 218  */
 219 WS_DLL_PUBLIC
 220 void
 221 wmem_cleanup(void);
 222
 223 WS_DLL_PUBLIC
 224 void
 225 wmem_enter_scope(wmem_allocator_t *allocator);
 226
 227 WS_DLL_PUBLIC
 228 void
 229 wmem_leave_scope(wmem_allocator_t *allocator);
 230
 231 WS_DLL_PUBLIC
 232 bool
 233 wmem_in_scope(wmem_allocator_t *allocator);
 234
 235 /** @} */
 236
 237 #ifdef __cplusplus
 238 }
 239 #endif /* __cplusplus */
 240
 241 #endif /* __WMEM_CORE_H__ */
 242
 243 /*
 244  * Editor modelines  -  https://www.wireshark.org/tools/modelines.html
 245  *
 246  * Local variables:
 247  * c-basic-offset: 4
 248  * tab-width: 8
 249  * indent-tabs-mode: nil
 250  * End:
 251  *
 252  * vi: set shiftwidth=4 tabstop=8 expandtab:
 253  * :indentSize=4:tabSize=8:noTabs=true:
 254  */