diff options
| -rw-r--r-- | doc/README.wmem | 34 | ||||
| -rw-r--r-- | doc/rawshark.pod | 8 | ||||
| -rw-r--r-- | doc/tshark.pod | 8 | ||||
| -rw-r--r-- | doc/wireshark.pod.template | 8 |
4 files changed, 51 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 diff --git a/doc/rawshark.pod b/doc/rawshark.pod index 69be6aba0d..cc47174e22 100644 --- a/doc/rawshark.pod +++ b/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 diff --git a/doc/tshark.pod b/doc/tshark.pod index 087d75b8eb..24d62c6f41 100644 --- a/doc/tshark.pod +++ b/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 diff --git a/doc/wireshark.pod.template b/doc/wireshark.pod.template index c356e2e55b..9f1e72aa02 100644 --- a/doc/wireshark.pod.template +++ b/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 |