doc/README.wmem

   1 $Id$
   2
   3 1. Introduction
   4
   5 NB: Wmem still does not provide all of the functionality of emem
   6     (see README.malloc), although it should provide most of it. New code
   7     may still need to use emem for the time being.
   8
   9 The 'emem' memory manager (described in README.malloc) has been a part of
  10 Wireshark since 2005 and has served us well, but is starting to show its age.
  11 The framework has become increasingly difficult to maintain, and limitations
  12 in the API have blocked progress on other long-term goals such as multi-
  13 threading, and opening multiple files at once.
  14
  15 The 'wmem' memory manager is an attempt to write a new memory management
  16 framework to replace emem. It provides a significantly updated API, a more
  17 modular design, and it isn't all jammed into one 2500-line file.
  18
  19 Wmem was originally conceived in this email to the wireshark-dev mailing list:
  20 https://www.wireshark.org/lists/wireshark-dev/201210/msg00178.html
  21
  22 The wmem code can now be found in epan/wmem/ in the Wireshark source tree.
  23
  24 2. Usage for Consumers
  25
  26 If you're writing a dissector, or other "userspace" code, then using wmem
  27 should be very similar to using emem. All you need to do is include the header
  28 (epan/wmem/wmem.h) and get a handle to a memory pool (if you want to *create*
  29 a memory pool, see the section "3. Usage for Producers" below).
  30
  31 A memory pool is an opaque pointer to an object of type wmem_allocator_t, and
  32 it is the very first parameter passed to almost every call you make to wmem.
  33 Other than that parameter (and the fact that functions are prefixed wmem_
  34 instead of ep_ or se_) usage is exactly like that of emem. For example:
  35
  36     wmem_alloc(myPool, 20);
  37
  38 allocates 20 bytes in the pool pointed to by myPool.
  39
  40 2.1 Available Pools
  41
  42 2.1.1 (Sort Of) Global Pools
  43
  44 Dissectors that include the wmem header file will have three pools available
  45 to them automatically: wmem_packet_scope(), wmem_file_scope() and
  46 wmem_epan_scope();
  47
  48 The packet pool is scoped to the dissection of each packet, replacing
  49 emem's ep_ allocators. The file pool is scoped to the dissection of each file,
  50 replacing emem's se_ allocators. For example:
  51
  52     ep_malloc(32);
  53     se_malloc(sizeof(guint));
  54
  55 could be replaced with
  56
  57     wmem_alloc(wmem_packet_scope(), 32);
  58     wmem_alloc(wmem_file_scope(),   sizeof(guint));
  59
  60 NB: Using these pools outside of the appropriate scope (eg using the packet
  61     pool when there isn't a packet being dissected) will throw an assertion.
  62     See the comment in epan/wmem/wmem_scopes.c for details.
  63
  64 The epan pool is scoped to the library's lifetime - memory allocated in it is
  65 not freed until epan_cleanup() is called, which is typically at the end of the
  66 program.
  67
  68 2.1.2 Pinfo Pool
  69
  70 Certain places (such as AT_STRINGZ address allocations) need their memory to
  71 stay around a little longer than the usual packet scope - basically until the
  72 next packet is dissected. This is effectively the scope of Wireshark's pinfo
  73 structure, so the pinfo struct has a 'pool' member which is a wmem pool scoped
  74 to the lifetime of the pinfo struct.
  75
  76 2.2 Core API
  77
  78  - wmem_alloc
  79  - wmem_alloc0
  80
  81 2.3 String Utilities
  82
  83  - wmem_strdup
  84  - wmem_strndup
  85  - wmem_strdup_printf
  86  - wmem_strdup_vprintf
  87
  88 2.4 Stack
  89
  90  - wmem_stack_new
  91  - wmem_stack_push
  92  - wmem_stack_pop
  93  - wmem_stack_peek
  94  - wmem_stack_count
  95
  96 2.5 Singly-Linked List
  97
  98  - wmem_slist_new
  99  - wmem_slist_prepend
 100  - wmem_slist_remove
 101  - wmem_slist_front
 102  - wmem_slist_frame_next
 103  - wmem_slist_frame_data
 104  - wmem_slist_count
 105
 106 2.6 Slab
 107
 108  - wmem_slab_new
 109  - wmem_slab_alloc
 110  - wmem_slab_free
 111
 112 2.7 String-Buffers
 113
 114  - wmem_strbuf_new
 115  - wmem_strbuf_sized_new
 116  - wmem_strbuf_append
 117  - wmem_strbuf_get_str
 118  - wmem_strbuf_get_len
 119
 120 3. Usage for Producers
 121
 122 NB: If you're just writing a dissector, you probably don't need to read
 123     this section.
 124
 125 One of the problems with the old emem framework was that there were basically
 126 two allocator backends (glib and mmap) that were all mixed together in a mess
 127 of if statements, environment variables and #ifdefs. In wmem the different
 128 allocator backends are cleanly separated out, and it's up to the owner of the
 129 pool to pick one.
 130
 131 3.1 Available Allocator Back-Ends
 132
 133 Each available allocator type has a corresponding entry in the
 134 wmem_allocator_type_t enumeration defined in wmem_core.h.
 135
 136 The currently available allocators are:
 137  - WMEM_ALLOCATOR_SIMPLE (wmem_allocator_simple.*)
 138         A trivial allocator that g_allocs requested memory and tracks
 139         allocations via a simple linked list.
 140  - WMEM_ALLOCATOR_BLOCK (wmem_allocator_block.*)
 141         A block allocator that grabs large chunks of memory at a time
 142         (8 MB currently) and serves allocations out of those chunks.
 143
 144 3.2 Creating a Pool
 145
 146 To create a pool, include the regular wmem header and call the
 147 wmem_allocator_new() function with the appropriate type value.
 148 For example:
 149
 150     #include "wmem/wmem.h"
 151
 152     wmem_allocator_t *myPool;
 153     myPool = wmem_allocator_new(WMEM_ALLOCATOR_SIMPLE);
 154
 155 From here on in, you don't need to remember which type of allocator you used
 156 (although allocator authors are welcome to expose additional allocator-specific
 157 helper functions in their headers). The "myPool" variable can be passed around
 158 and used as normal in allocation requests as described in section 2 of this
 159 document.
 160
 161 3.3 Destroying a Pool
 162
 163 Regardless of which allocator you used to create a pool, it can be destroyed
 164 with a call to the function wmem_destroy_allocator(). For example:
 165
 166     #include "wmem/wmem.h"
 167
 168     wmem_allocator_t *myPool;
 169
 170     myPool = wmem_allocator_new(WMEM_ALLOCATOR_SIMPLE);
 171
 172     /* Allocate some memory in myPool ... */
 173
 174     wmem_destroy_allocator(myPool);
 175
 176 Destroying a pool will free all the memory allocated in it.
 177
 178 3.4 Reusing a Pool
 179
 180 It is possible to free all the memory in a pool without destroying it,
 181 allowing it to be reused later. Depending on the type of allocator, doing this
 182 (by calling wmem_free_all()) can be significantly cheaper than fully destroying
 183 and recreating the pool. This method is therefore recommended, especially when
 184 the pool would otherwise be scoped to a single iteration of a loop. For example:
 185
 186     #include "wmem/wmem.h"
 187
 188     wmem_allocator_t *myPool;
 189
 190     myPool = wmem_allocator_new(WMEM_ALLOCATOR_SIMPLE);
 191     for (...) {
 192
 193         /* Allocate some memory in myPool ... */
 194
 195         /* Free the memory, faster than destroying and recreating
 196            the pool each time through the loop. */
 197         wmem_free_all(myPool);
 198     }
 199     wmem_destroy_allocator(myPool);
 200
 201 4. Internal Design
 202
 203 Despite being written in Wireshark's standard C90, wmem follows a fairly
 204 object-oriented design pattern. Although efficiency is always a concern, the
 205 primary goals in writing wmem were maintainability, and preventing memory
 206 leaks.
 207
 208 4.1 struct _wmem_allocator_t
 209
 210 The heart of wmem is the _wmem_allocator_t structure defined in the
 211 wmem_allocator.h header file. This structure uses C function pointers to
 212 implement a common object-oriented pattern known as an interface (AKA 'abstract
 213 class' to those of you who are more familiar with C++).
 214
 215 Different allocator implementations can provide exactly the same interface by
 216 assigning their own functions (of the appropriate signature) to the members of
 217 an instance of the structure. The structure currently has four values:
 218
 219  - alloc()
 220  - free_all()
 221  - destroy()
 222  - private_data
 223
 224 The private_data pointer is a void pointer that the implementation can use to
 225 store whatever internal structures it needs. The other three functions should
 226 be fairly obvious - each one is called with a pointer to the private_data in
 227 addition to any other arguments.
 228
 229 4.2 Pool-Agnostic API
 230
 231 One of the issues with emem was that the API (including the public data
 232 structures) required wrapper functions for each scope implemented. Even
 233 if there was a stack implementation in emem, it wasn't necessarily available
 234 for use with file-scope memory unless someone took the time to write se_stack_
 235 wrapper functions for the interface.
 236
 237 In wmem, all public APIs take the pool as the first argument, so that they can
 238 be written once and used with any available memory pool. Data structures like
 239 wmem's stack implementation only take the pool when created - the provided
 240 pointer is stored internally with the data structure, and subsequent calls
 241 (like push and pop) will take the stack itself instead of the pool.
 242
 243 5. TODO List
 244
 245 The following is an incomplete list of things that emem provides but wmem has
 246 not yet implemented:
 247
 248  - strbuf
 249  - red-black tree
 250  - tvb_memdup
 251  - canaries
 252
 253 The following is a list of things that emem doesn't provide but that it might
 254 be nice if wmem did provide them:
 255
 256  - radix tree
 257  - dynamic array
 258  - realloc
 259
 260 /*
 261  * Editor modelines  -  http://www.wireshark.org/tools/modelines.html
 262  *
 263  * Local variables:
 264  * c-basic-offset: 4
 265  * tab-width: 8
 266  * indent-tabs-mode: nil
 267  * End:
 268  *
 269  * vi: set shiftwidth=4 tabstop=8 expandtab:
 270  * :indentSize=4:tabSize=8:noTabs=true:
 271  */