HEAP_FREE

The HEAP_FREE procedure recursively frees all heap variables (pointers or objects) referenced by its input argument. This routine examines the input variable, including all array elements and structure fields. When a valid pointer or object reference is encountered, that heap variable is marked for removal. Pointer references are then recursively examined for additional heap variables to be freed. (HEAP_FREE does not descend into object references; freeing resources contained by an object should be handled by the object's Cleanup method.) Finally, all heap variables identified by HEAP_FREE are released; pointer heap variables as if the PTR_FREE procedure was called, and object heap variables as if the OBJ_DESTROY procedure was called.

Note: If automatic garbage collection is enabled, heap variables are freed automatically when their reference counts reach zero. Automatic garbage collection is a more robust mechanism for finding and freeing orphaned heap variables than the older HEAP_FREE procedure, since automatic garbage collection will only free heap variables that have no remaining references.

See Automatic Garbage Collectionfor details.)

As with the related HEAP_GC procedure, there are some disadvantages to using HEAP_FREE:

When freeing object heap variables, HEAP_FREE calls OBJ_DESTROY without supplying any plain arguments or keywords. It is the responsibility of the object’s Cleanup method to release any heap variables encapsulated in the object itself; HEAP_FREE will not “descend” into an object to free heap variables.

Depending on the objects being released, calling OBJ_DESTROY (and thus the object’s Cleanup method) without parameters may not be sufficient. In such cases, call OBJ_DESTROY explicitly with the proper arguments rather than using HEAP_FREE.

HEAP_FREE releases the referenced heap variables in an unspecified order which depends on the current state of the internal data structure used by IDL to hold them. This can be confusing for object destructor methods that expect all of their contained data to be present. If your application requires a specific order for the release of its heap variables, you must explicitly free them in the correct order. HEAP_FREE cannot be used in such cases.
The algorithm used by HEAP_FREE to release variables requires examination of every existing heap variable (that is, it is an O(n) algorithm). This may be slow if an IDL session has thousands of current heap variables.

For these reasons, applications should keep careful track of their heap variable usage, and explicitly free them at the proper time (for example, using the object destructor method) rather than resorting to simple-looking but potentially expensive expedients such as HEAP_FREE or HEAP_GC.

HEAP_FREE is recommended when:

The data structures involved are highly complex, nested, or variable, and writing cleanup code is difficult and error prone.
The data structures are opaque, and the code cleaning up does not have knowledge of the structure.

Examples

; Create a structure variable.
mySubStructure = {pointer:PTR_NEW(INDGEN(100)), $
obj:OBJ_NEW('Idl_Container')}
myStructure ={substruct:mySubStructure, $
ptrs:[PTR_NEW(INDGEN(10)), PTR_NEW(INDGEN(11))]}

;Look at the heap.
HELP, /HEAP_VARIABLES

; Now free the heap variables contained in myStructure.
HEAP_FREE, myStructure, /VERBOSE
HELP, /HEAP_VARIABLES

Syntax

HEAP_FREE, Var [, /OBJ] [, /PTR] [, /VERBOSE]

Arguments

Var

The variable whose data is used as the starting point for heap variables to be freed.

Keywords

OBJ

Set this keyword to free object heap variables only.

PTR

Set this keyword to free pointer heap variables only.

Note: Setting both the PTR and OBJ keywords is the same as setting neither.

VERBOSE

If this keyword is set, HEAP_FREE writes a one line description of each heap variable, in the format used by the HELP procedure, as the variable is released. This is a debugging aid that can be used by program developers to check for heap variable leaks that need to be located and eliminated.

Version History

5.3	Introduced