Root > Reference > All Functions > DumpAllocationsToFile

Procedure DumpAllocationsToFile

Previous pageReturn to chapter overviewNext page   

Logs all allocated memory to file.

 

Unit

EMemLeaks

 

Syntax

 

Code (Delphi)

procedure DumpAllocationsToFile(

const AFileName: String;

const ACount: Boolean = True;

const AGroup: Boolean = True;

const AGroupHeuristic: Boolean = True;

const ASort: Boolean = True;

const AFilter: TDumpFilterFunc = nil;

const ACompare: TDumpCompareFunc = nil;

const ACompareForCount: TDumpCompareFunc = nil

);

 

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.

Tip

You can use parenting (see above) to eliminate such cases.

 

 

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.

 

Tip

EurekaLog is capable of extracting class name from objects and "Name" property from components. Use custom names for other types of memory blocks.

 

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).

 

Tip

The function will log only memory blocks allocated via EurekaLog's memory filter with enabled registering memory leaks.

 

Warning

This function will block all memory operations during logging. Also, the logging takes a lot of time to complete. Do not call this routine in production. This function is designed to be called for local debugging purposes only. I.e. call this routine to locate known memory leak issue.

 

Warning

While your application may work after calling this function, it is best to terminate the process immediatelly after calling this function.

 

For technical reasons heap memory may not be in valid state after calling this function. Thus, you may encounter memory-related crashes.

 

See also




Send feedback... Build date: 2018-11-26
Last edited: 2018-11-26
PRIVACY STATEMENT
The documentation team uses the feedback submitted to improve the EurekaLog documentation. We do not use your e-mail address for any other purpose. We will remove your e-mail address from our system after the issue you are reporting has been resolved. While we are working to resolve this issue, we may send you an e-mail message to request more information about your feedback. After the issues have been addressed, we may send you an email message to let you know that your feedback has been addressed.


Permanent link to this article: https://www.eurekalog.com/help/eurekalog/topic_function_ememleaks_dumpallocationstofile.php