epan/wmem/wmem_core.h

   1 /* wmem_core.h
   2  * Definitions for the Wireshark Memory Manager Core
   3  * Copyright 2012, Evan Huus <eapache@gmail.com>
   4  *
   5  * $Id$
   6  *
   7  * Wireshark - Network traffic analyzer
   8  * By Gerald Combs <gerald@wireshark.org>
   9  * Copyright 1998 Gerald Combs
  10  *
  11  * This program is free software; you can redistribute it and/or modify
  12  * it under the terms of the GNU General Public License as published by
  13  * the Free Software Foundation; either version 2 of the License, or
  14  * (at your option) any later version.
  15  *
  16  * This program is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19  * GNU General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU General Public License along
  22  * with this program; if not, write to the Free Software Foundation, Inc.,
  23  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  24  */
  25
  26 #ifndef __WMEM_CORE_H__
  27 #define __WMEM_CORE_H__
  28
  29 #include <string.h>
  30 #include <glib.h>
  31 #include <ws_symbol_export.h>
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif /* __cplusplus */
  36
  37 /** @defgroup wmem Wireshark Memory Manager
  38  *
  39  * Wmem is a memory management framework for Wireshark that makes it simple to
  40  * write dissectors (and other 'user-space' code) that doesn't leak memory. The
  41  * core module provides basic functions like malloc, realloc and free, but
  42  * many other functions are available (see the "Modules" list at the top of
  43  * the generated doxygen HTML).
  44  *
  45  * @{
  46  */
  47
  48 struct _wmem_allocator_t;
  49 /** A public opaque type representing one wmem allocation pool. */
  50 typedef struct _wmem_allocator_t wmem_allocator_t;
  51
  52 /** An enumeration of the different types of available allocators. */
  53 typedef enum _wmem_allocator_type_t {
  54     WMEM_ALLOCATOR_SIMPLE, /**< A trivial allocator that mallocs requested
  55                memory and tracks allocations via a hash table. As simple as
  56                possible, intended more as a demo than for practical usage. Also
  57                has the benefit of being friendly to tools like valgrind. */
  58     WMEM_ALLOCATOR_BLOCK, /**< A block allocator that grabs large chunks of
  59                 memory at a time (8 MB currently) and serves allocations out of
  60                 those chunks. Designed for efficiency, especially in the
  61                 free_all operation. */
  62     WMEM_ALLOCATOR_STRICT /**< An allocator that does its best to find invalid
  63                 memory usage via things like canaries and scrubbing freed
  64                 memory. Valgrind is the better choice on platforms that support
  65                 it. */
  66 } wmem_allocator_type_t;
  67
  68 /** Allocate the requested amount of memory in the given pool.
  69  *
  70  * @param allocator The allocator object to use to allocate the memory.
  71  * @param size The amount of memory to allocate.
  72  * @return A void pointer to the newly allocated memory.
  73  */
  74 WS_DLL_PUBLIC
  75 void *
  76 wmem_alloc(wmem_allocator_t *allocator, const size_t size)
  77 G_GNUC_MALLOC;
  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 /** Allocate memory sufficient to hold n objects of the given type.
  89  *
  90  * @param allocator The allocator object to use to allocate the memory.
  91  * @param type The type that the newly allocated memory will hold.
  92  * @param num  The number of objects that the newly allocated memory will hold.
  93  * @return A void pointer to the newly allocated memory.
  94  */
  95 #define wmem_alloc_array(allocator, type, num) \
  96     ((type*)wmem_alloc((allocator), sizeof(type) * (num)))
  97
  98 /** Allocate the requested amount of memory in the given pool. Initializes the
  99  * allocated memory with zeroes.
 100  *
 101  * @param allocator The allocator object to use to allocate the memory.
 102  * @param size The amount of memory to allocate.
 103  * @return A void pointer to the newly allocated and zeroed memory.
 104  */
 105 WS_DLL_PUBLIC
 106 void *
 107 wmem_alloc0(wmem_allocator_t *allocator, const size_t size)
 108 G_GNUC_MALLOC;
 109
 110 /** Allocate memory sufficient to hold one object of the given type.
 111  * Initializes the allocated memory with zeroes.
 112  *
 113  * @param allocator The allocator object to use to allocate the memory.
 114  * @param type The type that the newly allocated memory will hold.
 115  * @return A void pointer to the newly allocated and zeroed memory.
 116  */
 117 #define wmem_new0(allocator, type) \
 118     ((type*)wmem_alloc0((allocator), sizeof(type)))
 119
 120 /** Allocate memory sufficient to hold n objects of the given type.
 121  * Initializes the allocated memory with zeroes.
 122  *
 123  * @param allocator The allocator object to use to allocate the memory.
 124  * @param type The type that the newly allocated memory will hold.
 125  * @param num  The number of objects that the newly allocated memory will hold.
 126  * @return A void pointer to the newly allocated and zeroed memory.
 127  */
 128 #define wmem_alloc0_array(allocator, type, num) \
 129     ((type*)wmem_alloc0((allocator), sizeof(type) * (num)))
 130
 131 /** Returns the allocated memory to the allocator. This function should only
 132  * be called directly by allocators when the allocated block is sufficiently
 133  * large that the reduced memory usage is worth the cost of the extra function
 134  * call. It's usually easier to just let it get cleaned up when wmem_free_all()
 135  * is called.
 136  *
 137  * @param allocator The allocator object used to originally allocate the memory.
 138  * @param ptr The pointer to the memory block to free. After this function
 139  * returns it no longer points to valid memory.
 140  */
 141 WS_DLL_PUBLIC
 142 void
 143 wmem_free(wmem_allocator_t *allocator, void *ptr);
 144
 145 /** Resizes a block of memory, potentially moving it if resizing it in place
 146  * is not possible.
 147  *
 148  * @param allocator The allocator object used to originally allocate the memory.
 149  * @param ptr The pointer to the memory block to resize.
 150  * @param size The new size for the memory block.
 151  * @return The new location of the memory block. If this is different from ptr
 152  * then ptr no longer points to valid memory.
 153  */
 154 WS_DLL_PUBLIC
 155 void *
 156 wmem_realloc(wmem_allocator_t *allocator, void *ptr, const size_t size)
 157 G_GNUC_MALLOC;
 158
 159 /** Frees all the memory allocated in a pool. Depending on the allocator
 160  * implementation used this can be significantly cheaper than calling
 161  * wmem_free() on all the individual blocks. It also doesn't require you to have
 162  * external pointers to those blocks.
 163  *
 164  * @param allocator The allocator to free the memory from.
 165  */
 166 WS_DLL_PUBLIC
 167 void
 168 wmem_free_all(wmem_allocator_t *allocator);
 169
 170 /** Triggers a garbage-collection in the allocator. This does not free any
 171  * memory, but it can return unused blocks to the operating system or perform
 172  * other optimizations.
 173  *
 174  * @param allocator The allocator in which to trigger the garbage collection.
 175  */
 176 WS_DLL_PUBLIC
 177 void
 178 wmem_gc(wmem_allocator_t *allocator);
 179
 180 /** Destroy the given allocator, freeing all memory allocated in it. Once this
 181  * function has been called, no memory allocated with the allocator is valid.
 182  *
 183  * @param allocator The allocator to destroy.
 184  */
 185 WS_DLL_PUBLIC
 186 void
 187 wmem_destroy_allocator(wmem_allocator_t *allocator);
 188
 189 /** Create a new allocator of the given type. The type may be overridden by the
 190  * WIRESHARK_DEBUG_WMEM_OVERRIDE environment variable.
 191  *
 192  * @param type The type of allocator to create.
 193  * @return The new allocator.
 194  */
 195 WS_DLL_PUBLIC
 196 wmem_allocator_t *
 197 wmem_allocator_new(const wmem_allocator_type_t type);
 198
 199 /** Initialize the wmem subsystem. This must be called before any other wmem
 200  * function, usually at the very beginning of your program.
 201  */
 202 WS_DLL_PUBLIC
 203 void
 204 wmem_init(void);
 205
 206 /** Teardown the wmem subsystem. This must be called after all other wmem
 207  * functions, usually at the very end of your program. This function will not
 208  * destroy outstanding allocators, you must do that yourself.
 209  */
 210 WS_DLL_PUBLIC
 211 void
 212 wmem_cleanup(void);
 213
 214 /** @} */
 215
 216 #ifdef __cplusplus
 217 }
 218 #endif /* __cplusplus */
 219
 220 #endif /* __WMEM_CORE_H__ */
 221
 222 /*
 223  * Editor modelines  -  http://www.wireshark.org/tools/modelines.html
 224  *
 225  * Local variables:
 226  * c-basic-offset: 4
 227  * tab-width: 8
 228  * indent-tabs-mode: nil
 229  * End:
 230  *
 231  * vi: set shiftwidth=4 tabstop=8 expandtab:
 232  * :indentSize=4:tabSize=8:noTabs=true:
 233  */