6.1 Keys

This section describes the keys and values in the LeapHeap registry interface.

For some imaginary application that runs as the executable file 'application.exe', the root of the LeapHeap tree is created at HKEY_CURRENT_USER\Software\LeapHeap\application.exe. There are two branches of the tree. HKEY_CURRENT_USER\Software\LeapHeap\application.exe\Log contains values written by LeapHeap every time the application runs. HKEY_CURRENT_USER\Software\LeapHeap\application.exe\Settings contains values writeable by the administrator. If LeapHeap is unable to find the right subkeys and values when it initialises, it creates them and sets them to defaults, so the administrator never has to add keys manually. If mistakes are made when editing the registry and it gets in a tangle, it is easy to delete the entire key subtree for the application in question; the defaults will be restored the next time the application runs.

All the values in the LeapHeap portion of the registry are of type REG_SZ (simple string). Subkey names, value names and data are processed by LeapHeap in a case-independent fashion. A datum parsed as a number may bear the prefix "0x" to denote a hexadecimal number.

A full list of subkeys and values, paths shown relative to the root key of the application, follows:

Key:Log

Value:ErrorMessage

A diagnostic message if an error has been detected, otherwise the empty string.

Value:ErrorStatus

"Error" if an error has been detected, otherwise "OK".

Value:LastExecutedAt

The date and time when the application was last invoked e.g."2004 Aug 03 08:21:10".

Value:HeapCreateCount

The number of calls to HeapCreate that the application has made, plus one for the process heap e.g. "5". Like all the values under this key, it is only updated if the Logging value of the Settings key is "ON".

Value:HeapDestroyCount

The number of calls to HeapDestroy that the application has made e.g. "2".

Value:HeapsInUse

HeapCreateCount less HeapDestroyCount e.g. "3". A redundant value.

Value:MaxHeapsInUse

The maximum that HeapsInUse has attained since the application started e.g. "4".

Key:Log\HighWaterMark

Monitors the use the application is making of LeapHeap compartment and big-block area memory. This key is only updated if the Logging value of the Settings key is "ON", otherwise all values are removed. The key holds one BigBlockMemory value and one BigBlockCount value, plus a additional value for each defined compartment. The additional values take the form e.g. Sizeclass007 if the compartment maps to one sizeclass or e.g. Sizeclass008To012 if it maps to several. The data held by each value measure the proportion of the compartment (or big-block area) that has been used at maximum extent e.g. "37%".

Value:Logging

Either "ON" or "OFF". Controls the reporting of compartment highwater marks and heap creation and destruction.

Value:Validation

Either "ON" or "OFF". Determines whether the LeapValidate routine performs cell bitmap consistency checking, as described in section 4.7 API Conformance.

Key:Settings\CompartmentSizes

Fixes the size of the memory compartments that LeapHeap creates when it initialises. Contains values of the form Rule01, Rule02, ...Rule99, Rule100 etc.. but usually no more than half a dozen rules are needed. Only the 'rule' values are processed, and then only so far as they are strictly in sequence starting at Rule01. Other values under the key are ignored. If LeapHeap cannot find the value Rule01, it writes its own default rules into the key. If the data of a rule have the form "bigblockarea n" where n is a positive integer, that sets the size of the LeapHeap big-block area in megabytes. If a rule of this form is not present, LeapHeap uses its own default of 10 MB. Otherwise, the data must have one of the forms "Sizeclass m Tiers t" or "Sizeclass m To n Tiers t", where m and n are integers between 1 and 512 inclusive with m<=n and t is an integer between 1 and 5 inclusive. The effect of a rule of the latter form is to create a separate compartment with t cascading bitmap tiers and cell size i*8 for each integer i between m and n inclusive. The single-sizeclass form is a shorthand that can be used when n is the same as m. It is not an error to cover the same sizeclass in more than one rule; the last rule in sequence takes precedence.

Value:ExtendedDestroy

Either "ON" or "OFF". When switched on, heap identifier tagging is in force and LeapDestroy frees all cells 'belonging' to the heap to be destroyed. Otherwise LeapDestroy does nothing.

Value:FollowDestroyWithCompact

This value is only processed when ExtendedDestroy is on. If "ON", LeapDestroy calls LeapCompact after freeing cells, in order to release pagefile memory. The other legal option is "OFF".

Value:TagBits

This value is only processed when ExtendedDestroy is on. The possible options are "8" or "16", and determine how many bits are used to tag allocations with the identifier of the heap they purportedly belong to.