Document the wmem override environment variable in the man pages, and improve

README.wmem in a couple of places.

svn path=/trunk/; revision=48251

1 files changed, 27 insertions, 7 deletions

diff --git a/doc/README.wmem b/doc/README.wmem
index f8860d7071..420a6e872c 100644
--- a/doc/README.wmem
+++ b/doc/README.wmem
@@ -135,10 +135,13 @@ wmem_allocator_type_t enumeration defined in wmem_core.h.
 The currently available allocators are:
  - WMEM_ALLOCATOR_SIMPLE (wmem_allocator_simple.*)
         A trivial allocator that g_allocs requested memory and tracks
-        allocations via a GHashTable.
+        allocations via a GHashTable. As simple as possible, intended more as
+        a demo than for practical usage. Also has the benefit of being friendly
+        to tools like valgrind.
  - WMEM_ALLOCATOR_BLOCK (wmem_allocator_block.*)
         A block allocator that grabs large chunks of memory at a time
         (8 MB currently) and serves allocations out of those chunks.
+        Designed for efficiency, especially in the free_all operation.
  - WMEM_ALLOCATOR_STRICT (wmem_allocator_strict.*)
         An allocator that does its best to find invalid memory usage via
         things like canaries and scrubbing freed memory. Valgrind is the
@@ -161,12 +164,6 @@ 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.
 
-Note that the type of pool you request won't always be the type you get - the
-WIRESHARK_DEBUG_WMEM_OVERRIDE environment variable (if set) can be used to
-force all calls to wmem_allocator_new() to returns a specific type for debugging
-purposes. It will always be safe to call allocator-specific helpers though, they
-will simply be no-ops if the type doesn't match.
-
 3.3 Destroying a Pool
 
 Regardless of which allocator you used to create a pool, it can be destroyed
@@ -297,6 +294,29 @@ wmem's stack implementation only take the pool when created - the provided
 pointer is stored internally with the data structure, and subsequent calls
 (like push and pop) will take the stack itself instead of the pool.
 
+4.3 Debugging
+
+The primary debugging control for wmem is the WIRESHARK_DEBUG_WMEM_OVERRIDE
+environment variable. If set, this value forces all calls to
+wmem_allocator_new() to return the same type of allocator, regardless of which
+type is requested normally by the code. It currently has three valid values:
+
+ - The value "simple" forces the use of WMEM_ALLOCATOR_SIMPLE. The valgrind
+   script currently sets this value, since the simple allocator is the only
+   one whose memory allocations are trackable properly by valgrind.
+
+ - The value "strict" forces the use of WMEM_ALLOCATOR_STRICT. The fuzz-test
+   script currently sets this value, since the goal when fuzz-testing is to find
+   as many errors as possible.
+
+ - The value "block" forces the use of WMEM_ALLOCATOR_BLOCK. This is not
+   currently used by any scripts, but is useful for stress-testing the block
+   allocator.
+
+Note that regardless of the value of this variable, it will always be safe to
+call allocator-specific helpers functions. They are required to be safe no-ops
+if the allocator argument is of the wrong type.
+
 5. TODO List
 
 The following is a list of things that wmem provides but are incomplete