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

README.wmem in a couple of places.

svn path=/trunk/; revision=48251

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

doc/rawshark.pod

@@ -432,6 +432,14 @@ per-file memory is initialized to 0xBADDCAFE when the memory is allocated
 and is reset to 0xDEADBEEF when the memory is freed.  This functionality is
 useful mainly to developers looking for bugs in the way memory is handled.
 
+=item WIRESHARK_DEBUG_WMEM_OVERRIDE
+
+Setting this environment variable forces the wmem framework to use the
+specified allocator backend for *all* allocations, regardless of which
+backend is normally specified by the code. This is mainly useful to developers
+when testing or debugging. See I<README.wmem> in the source distribution for
+details.
+
 =item WIRESHARK_RUN_FROM_BUILD_DIRECTORY
 
 This environment variable causes the plugins and other data files to be loaded

doc/tshark.pod

@@ -1574,6 +1574,14 @@ per-file memory is initialized to 0xBADDCAFE when the memory is allocated
 and is reset to 0xDEADBEEF when the memory is freed.  This functionality is
 useful mainly to developers looking for bugs in the way memory is handled.
 
+=item WIRESHARK_DEBUG_WMEM_OVERRIDE
+
+Setting this environment variable forces the wmem framework to use the
+specified allocator backend for *all* allocations, regardless of which
+backend is normally specified by the code. This is mainly useful to developers
+when testing or debugging. See I<README.wmem> in the source distribution for
+details.
+
 =item WIRESHARK_RUN_FROM_BUILD_DIRECTORY
 
 This environment variable causes the plugins and other data files to be loaded

doc/wireshark.pod.template

@@ -2735,6 +2735,14 @@ per-file memory is initialized to 0xBADDCAFE when the memory is allocated
 and is reset to 0xDEADBEEF when the memory is freed.  This functionality is
 useful mainly to developers looking for bugs in the way memory is handled.
 
+=item WIRESHARK_DEBUG_WMEM_OVERRIDE
+
+Setting this environment variable forces the wmem framework to use the
+specified allocator backend for *all* allocations, regardless of which
+backend is normally specified by the code. This is mainly useful to developers
+when testing or debugging. See I<README.wmem> in the source distribution for
+details.
+
 =item WIRESHARK_RUN_FROM_BUILD_DIRECTORY
 
 This environment variable causes the plugins and other data files to be loaded