diff options
author | Evan Huus <eapache@gmail.com> | 2012-10-30 01:24:16 +0000 |
---|---|---|
committer | Evan Huus <eapache@gmail.com> | 2012-10-30 01:24:16 +0000 |
commit | 7588f1229167c5bdbe803dd80b6a4cce72d3c9c2 (patch) | |
tree | 370e9972ab897878f3b31ca0bb5d48766cac593f /doc/README.wmem | |
parent | 041fe5ef99e8ec307da8e031cb7e515c5d6a028f (diff) |
Some documentation for wmem.
svn path=/trunk/; revision=45832
Diffstat (limited to 'doc/README.wmem')
-rw-r--r-- | doc/README.wmem | 145 |
1 files changed, 145 insertions, 0 deletions
diff --git a/doc/README.wmem b/doc/README.wmem new file mode 100644 index 0000000000..6b030ded8a --- /dev/null +++ b/doc/README.wmem @@ -0,0 +1,145 @@ +$Id$ + +1. Introduction + +NB: Wmem is still very much incomplete and under construction. New code will + likely want to continue using emem for the time being. + +The 'emem' memory manager (described in README.malloc) has been a part of +Wireshark since 2005 and has served us well, but is starting to show its age. +The framework has become increasingly difficult to maintain, and limitations +in the API have blocked progress on other long-term goals (like multi- +threading, and opening multiple files at once). + +The 'wmem' memory manager is an attempt to write a new memory management +framework to replace emem. It provides a significantly updated API, a more +modular design, and it isn't all jammed into one 2500-line file. + +Wmem was originally conceived in this email to the wireshark-dev mailing list: +https://www.wireshark.org/lists/wireshark-dev/201210/msg00178.html + +The wmem code can now be found in epan/wmem/ in the Wireshark source tree. + +2. Usage for Consumers + +If you're writing a dissector, or other "userspace" code, then using wmem +should be very similar to using emem. All you need to do is include the header +(epan/wmem/wmem.h) and get a handle to a memory pool (if you want to *create* +a memory pool, see the section "3. Usage for Producers" below). + +A memory pool is an opaque pointer to an object of type wmem_allocator_t, and +it should be the very first parameter passed to *every* call you make to wmem. +Other than that (and the fact that functions are prefixed wmem_ instead of ep_ +or se_) usage is exactly like that of emem. For example: + + wmem_alloc(myPool, 20); + +allocates 20 bytes in the pool pointed to by myPool. + +2.1 Replacing Emem + +Once wmem is more complete, dissectors should have two pools avaiable to them: +one for packet scope and one for file scope (how to make these pools available +is still being debated). Requests for ep_ memory can be replaced with wmem +requests using the packet-scoped pool, and requests for se_ memory can be +replaced with wmem requests using the file-scoped pool. For example: + + ep_malloc(20); + +would become + + wmem_alloc(my_packet_pool, 20); + +3. Usage for Producers + +NB: If you're just writing a dissector, you probably don't need to read + this section. + +One of the problems with the old emem framework was that there were basically +two allocator backends (glib and mmap) that were all mixed together in a mess +of if statements, environment variables and even a few #ifdefs. In wmem each +of the allocator backends is cleanly separated out, and it's up to the +maintainer of the pool to pick one. + +3.1 Available Allocator Back-Ends + +The currently available allocators are: + - glib (wmem_allocator_glib.h) + A simple allocator that g_allocs requested memory and tracks each + allocation in a linked list. + +3.2 Creating a Pool + +To create a pool, include the header for the type of allocator you want to use +and call the create function available in that header. For example, + + #include "wmem/wmem_allocator_glib.h" + + wmem_allocator_t *myPool; + myPool = wmem_create_glib_allocator(); + +From here on in, you don't need to remember which type of allocator you used +(although allocator authors are welcome to expose additional allocator-specific +helper functions in their headers). The "myPool" variable can be passed around +and used as normal in allocation requests as described in section 2 of this +document. + +All the other functions in this section can be found in epan/wmem/wmem.h. + +3.3 Destroying a Pool + +Regardless of which allocator you used to create a pool, it can be destroyed +with a call to the function wmem_destroy_allocator(). For example: + + #include "wmem/wmem.h" + #include "wmem/wmem_allocator_glib.h" + + wmem_allocator_t *myPool; + + myPool = wmem_create_glib_allocator(); + + /* Allocate some memory in myPool ... */ + + wmem_destroy_allocator(myPool); + +Destroying a pool will free all the memory allocated in it. + +3.4 Reusing a Pool + +It is possible to free all the memory in a pool without destroying it, +allowing it to be reused later. This can be useful if you have a loop you +wish to allocate memory in, but you don't want to pay the cost of destroying +and creating an entire pool each time. + +The memory of a pool can be freed with a call to wmem_free_all(), like so: + + #include "wmem/wmem.h" + #include "wmem/wmem_allocator_glib.h" + + wmem_allocator_t *myPool; + + myPool = wmem_create_glib_allocator(); + for (...) { + + /* Allocate some memory in myPool ... */ + + wmem_free_all(myPool); + } + wmem_destroy_allocator(myPool); + +4. Internal Design + +TODO + +/* + * Editor modelines - http://www.wireshark.org/tools/modelines.html + * + * Local variables: + * c-basic-offset: 4 + * tab-width: 8 + * indent-tabs-mode: nil + * End: + * + * vi: set shiftwidth=4 tabstop=8 expandtab: + * :indentSize=4:tabSize=8:noTabs=true: + */ |