Add user callbacks to wmem. This feature is a generic way to transparently mimic

the behaviour emem has for seasonal trees, which is that the master tree
structure is not actually seasonal - it is permanent. When the seasonal memory
pool is cleared, the root node pointer in all of these permanent trees is set
to NULL, and the pool takes care of actually freeing the nodes.

Wmem can now mimic this by allocating the tree header struct in epan_scope(),
allocating any node structs in file_scope(), and registering a callback on
file_scope() that NULLs the pointer in the epan_scope() header. Yes, this is
confusing, but it seemed simpler than adding manual callback registrations to
every single dissector that currently uses seasonal trees.

The callbacks may also be useful for other things that need cleanup (I'm
thinking resource handles stored in wmem memory that need to be fclosed or
what-have-you before they the handle is lost).

As indicated by the number of caveats in README.wmem, the implementation
probably needs a bit of work to make it safer/saner/more-useful. Thoughts
(or patches!) in this direction are more than welcome.

svn path=/trunk/; revision=49205

1 files changed, 31 insertions, 0 deletions

diff --git a/doc/README.wmem b/doc/README.wmem
index 13ed863818..67f9967564 100644
--- a/doc/README.wmem
+++ b/doc/README.wmem
@@ -102,6 +102,37 @@ wmem_slist.h
 wmem_stack.h
  - A stack implementation (push, pop, etc).
 
+2.3 Callbacks
+
+WARNING: You probably don't actually need these; use them only when you're
+         sure you understand the implications and the consequences.
+
+Sometimes (though hopefully rarely) it may be necessary to store data in a wmem
+pool that requires additional cleanup before it is freed. For example, perhaps
+you have a pointer to a file-handle that needs to be closed. In this case, you
+can register a callback with the wmem_register_cleanup_callback function
+declared in wmem_core.h.
+
+This function takes the usual allocator, a function pointer (see wmem_user_cb_t
+also in wmem_core.h) and a void user_data pointer. Every time the memory in a
+pool is freed, all registered cleanup functions are called first, being passed
+a pointer to the allocator as well as whatever user_data was registered with
+that callback.
+
+WARNING: Callback calling order is not defined, you cannot rely on a certain
+         callback being called before or after another (in practice at the
+         moment it's first-in-last-out, but that may change).
+
+WARNING: Callbacks are not cleared when they are called - they are only cleared
+         when the pool is fully destroyed. (Do we need an unregister function?).
+
+WARNING: The user_data pointer is not freed when a callback is cleared, you
+         have to do that yourself (or just allocate it in the appropriate wmem
+         pool).
+
+WARNING: Calling wmem_free on allocated memory that a callback depends on will
+         not unregister that callback. Do not do this, it will crash!
+
 3. Usage for Producers
 
 NB: If you're just writing a dissector, you probably don't need to read