Monitoring RAM and Heap

Heap, RAM and disk status of your user's computer can be logged using inline or standalone tags.

In order to survey the memory evolution between parts of the code, THotLog provides another way of monitoring the first two (Heap and RAM), which values may change often, with four additionnal functions:

Function HeapMonitor(hmExtra: String=''; directOutput: Boolean=False) : THeapMRec;

hmExtra is a user defined string that may be added to the end of the (first) line of outputed values. As long as standalone tags are parsed in one "pass" only, hmExtra cannot be an inline tag, but only a string.
If directOutput is set, values won't be stored. The HeapTable will stay unchanged.

Procedure ResetHeapTable;

Empties the heap monitoring table

As long as they do work in a close maner, only heap monitoring will be detailed here.

hLog.HeapMonitor( ) will read heap values and request the parser thread to store them in a FIFO table. They'll be outputed when you'll pass heap outputing tags to the hLog.Add( ); function.

This table has 4 entires : three to store measures, and one to store an additional string that can be kept empty, a kind of free comment. If provided, It will be added at the end of the first line, when the standalone tag is used, after the values when inline tags are used.

Both HeapMonitor( ); and RamMonitor( ); return a THeapMRec record with the values just read:

THeapMRec = record
  Extra: string;
  case integer of
    // Heap
    {$IFDEF FPC}         // Lazarus
    0: (MaxHeapSize:                     PtrUInt;  // Maximium allowed size for the heap, in bytes
        MaxHeapUsed:                     PtrUInt;  // Maximum used size for the heap, in bytes
        CurrHeapSize:                    PtrUInt;  // Current heap size, in bytes
        CurrHeapUsed:                    PtrUInt;  // Currently used heap size, in bytes
        CurrHeapFree:                    PtrUInt); // Currently free memory on heap, in bytes
    {$ELSE}              // Delphi
    0: (AllocatedSmallBlockCount:        cardinal;
        TotalAllocatedSmallBlockSize:    NativeUInt;
        ReservedSmallBlockAddressSpace:  NativeUInt;
        AllocatedMediumBlockCount:       cardinal;
        TotalAllocatedMediumBlockSize:   NativeUInt;
        ReservedMediumBlockAddressSpace: NativeUInt;
        AllocatedLargeBlockCount:        cardinal;
        TotalAllocatedLargeBlockSize:    NativeUInt;
        ReservedLargeBlockAddressSpace:  NativeUInt);
    {$ENDIF}
    // Ram
    1: (MemoryLoad:                      cardinal;
        TotalPhysical:                   UInt64;
        AvailPhysical:                   UInt64;
        TotalPageFile:                   UInt64;
        AvailPageFile:                   UInt64;
        TotalVirtual:                    UInt64;
        AvailVirtual:                    UInt64);
  end;

Returned (and stored) values depend on the function called.
The return code of the function is stored into hExtra, under the form of a '0' if the function failed, a '1' otherwise. This means that you can check the result using function StrToBool(yourVariable.hExtra).

xxxMonitor( ); returns a THeapMRec (RAM or heap datalayout):

	HeapMonitor( ); (Delphi)	HeapMonitor( ); (Lazarus)	RamMonitor( );
Number	AllocatedSmallBlockCount
Bytes	TotalAllocatedSmallBlockSize	MaxHeapSize	TotalPhysical
Bytes	ReservedSmallBlockAddressSpace	MaxHeapUsed	AvailPhysical
Number	AllocatedMediumBlockCount
Bytes	TotalAllocatedMediumBlockSize	CurrHeapSize	TotalPageFile
Bytes	ReservedMediumBlockAddressSpace	CurrHeapUsed	AvailPageFile
Number	AllocatedLargeBlockCount
Bytes	TotalAllocatedLargeBlockSize	CurrHeapFree	TotalVirtual
Bytes	ReservedLargeBlockAddressSpace		AvailVirtual
%			MemoryLoad
Extra	'1'-> True or '0'-> False		'1'-> True or '0'-> False

HotLog Heap monitoring table works in FIFO mode.

Values (blocks, bytes and the optional string) are stored and retrieved alltogether, "line by line".
A request to output an entry (through the appropriate tag) will retrieve the oldest entry of the table (entry[0]). If none exist, a direct read is made at that time, returning values less accurate than if they had been stored earlier. When an entry is read, it is removed from the table too.

An example of use, in pseudo-code could be:

// Filling the table:
Begin
  hLog.ResetHeapTable;         //makes sure the table is empty, before storing new values;
  hLog.HeapMonitor;            // hm[0]
  PrepareWork;
  hLog.HeapMonitor;            // hm[1]
  DoWork;
  hLog.HeapMonitor;            // hm[2]
  FreeEvthg;
  hLog.HeapMonitor;            // hm[3]
End;

// Then read and clear the table:
hLog.Add('State of the heap before starting job:      {50@}{Heap--}');
hLog.Add('State of the heap after PrepareWork:        {50@}{Heap--}');
hLog.Add('State of the heap after DoWork:             {50@}{Heap--}');
hLog.Add('State of the heap after freeing everything: {50@}{Heap--}');

These lines show that there is no direct acces to the entries stored.

hLog doesn't provide any methode to compute heap deltas. But you can store and use the values returned by the HeapMonitor function to do it.