Procedure DumpAllocationsToFile

Logs all allocated memory to file.

Unit

EMemLeaks

Syntax

Parameters

AFileName [in]

A fully qualified valid file name. File's folder must exists and be writable. File will be (re)created.

ACount [in, optional]

True - group duplicate memory blocks, False - report each memory block individually.

AGroup [in, optional]

True - group child blocks with parent, False - report all memory blocks.

AGroupHeuristic [in, optional]

True - group child blocks with parent objects by using call stack heuristic, False - group only explicitly parented blocks. This argument is ignored when AGroup is False.

ASort [in, optional]

True - sort memory blocks, default sort is: blocks with most count (i.e. same type and call stack) will be first, then blocks of bigger size, same size is sorted by type: first - objects, then dyn-arrays/strings, then RAW data; False - do not sort memory blocks, list blocks in order of allocation (older - first, newer - last).

AFilter [in, optional]

A custom filter for filtering out memory blocks.

ACompare [in, optional]

A custom comparator for sorting.

ACompareForCount [in, optional]

A custom comparator for counting. Positive and negative results are considered to be the same (e.g. "not equal"). (This argument could be the same as ACompare)

Remarks

This function will log all allocated memory blocks to the specified file. Each memory block will be logged with call stack, properties (i.e. name, type, size, count) and short memory dump. Additionally a total memory statistics will be written.

This is a diagnostic function which can be used to find reasons for high memory usage, collect memory usage statitics, find hidden memory leaks, etc.

Counting

DumpAllocationsToFile will count memory blocks. Memory blocks are considered to be the same if these blocks have the same size, same type, same name and same call stack (up to 6 lines). Same memory block will be grouped together - only first block will be logged (with its call stack, dump and properties). Other blocks will not be logged. Instead, a count will be added to a header of the first logged memory blocks.

You may override a default comparison method by specifying your own ACompareForCount.

Typically, you are interested in memory blocks with higher counts. For example, when memory block is allocated 400 times - it may be an indication that such memory blocks are not released when needed.

Parenting

DumpAllocationsToFile may group child leaks with parent leak. Any memory block can be declared as child memory block to another memory block - you can do this via MemLeaksSetParentBlock function or MemLeaksOwn function. Additionally, any memory allocated withing constructor of any object will be declared as child memory to this object - this is determinated by a heuristic check using call stacks.

Grouping by parent allows you to view a lot of memory blocks as a single object. This feature is used to simplify report: it filters out non-important entries, showing only root parent for all sub-children. The idea behind this: if parent is leaked - then all children are leaked as well. However, you are not interested in children leak, because there is no bug. The bug is leaked parent. Thus, we hide leaked children, show leaked parent, now you can easily identificate root cause for bug. You solve bug - no more parent leak, thus no more children leak. Of course, if parent is not leaking, but some child are leaking - a child will be included in report.

Filtering

If you get many unrelated memory blocks included in your report, then you can supply a custom filter function (AFilter) to remove any particular memory block from report. Since run-time address change on each application's launch, you can not use exact address to filter out memory blocks. You have to rely on block's size, type, call stack, name, or, perhaps, an allocation order.

Sorting

Not all memory blocks are equally interesting. For examples, RAW data are often allocated from objects. Thus, objects are usually more interesting than RAW data.

You can use sorting to spot interest blocks and place them first. Default sorting prefers repeated blocks (with higher count), then it prefers large blocks (by grouped total size, not size of single blocks), then comes block's type (object, array, string or RAW), named/unnamed.

You can also supply a custom comparator function (ACompare) to define your own preferred sort order.

Naming

Usually it is difficult to identificate memory blocks inside memory report. While there is a lot of information (call stack, type, size, dump) - this is not enough for many cases. For example, if memory is allocated in cycle (like "while" cycle to read a document and create entries for each document's block). Such memory blocks will look the same in report, it is not possible to distinguish between them.

You can use MemLeaksName or MemLeaksOwn functions to mark any memory block with arbitrary name tag. Name tag will be displayed in header for memory block in the report.

Sizing

Headers for memory blocks indicate two sizes: single and total. Single is a size of allocation for each memory block inside the entry. Total is size occupied by entire entry. For duplicate (repeated) blocks: total size = single size * count. For parent-child grouping: parent total size = single parent size + each(total child size).

See also