HEAP_REFCOUNT

The HEAP_REFCOUNT function returns the current reference count for a pointer or object reference (a heap variable). It can also be used to disable garbage collection for a heap variable, or for all heap variables.

Examples

; Create an array of heap pointers
ptr = PTRARR(3)
ptr[0] = PTR_NEW(10)
ptr[1] = PTR_NEW(20)
ptr[2] = PTR_NEW(30)
; Each pointer has a reference count of 1
PRINT, HEAP_REFCOUNT(ptr)

IDL prints:

1           1           1

; Automatic garbage collection destroys the pointer
ptr[0] = PTR_NEW()
; Create another reference to the heap variable pointed to
; by ptr[1]
ptrNew = ptr[1]
; The reference counts have changed
PRINT, HEAP_REFCOUNT(ptr)

IDL prints:

0           2           1

Syntax

Result = HEAP_REFCOUNT( [Heaprefs] [, /DISABLE] [, /ENABLE] [, IS_ENABLED=variable] )

Return Value

Returns a result of the same shape as the input argument, containing the current reference count for the associated heap variables. Invalid heap variables return a reference count of zero.

Arguments

Heaprefs

Heaprefs can either be a scalar or array of pointer or object references, or a scalar or array of integer heap identifiers. If Heaprefs is not supplied, the DISABLE, ENABLE, and IS_ENABLED keywords apply to the entire automatic garbage collection system for all heap variables.

Keywords

DISABLE

Set this keyword to disable automatic garbage collection for Heaprefs. If Heaprefs is not supplied, automatic garbage collection is disabled for all heap variables.

Note: If you disable reference counting for a particular heap variable or variables, then the reference count will still be incremented or decremented appropriately for those heap variables, but the heap variables will not be destroyed when the reference count reaches zero. If you then re-enable reference counting for those heap variables, and the reference count has reached zero, then the heap variables will be destroyed the next time they are accessed.

Note: If you disable reference counting for all heap variables, then the reference counts will no longer be incremented or decremented. If you then re-enable reference counting, the reference counts for any existing heap variables may be incorrect, and these heap variables may be unexpectedly destroyed.

ENABLE

Set this keyword to re-enable automatic garbage collection for Heaprefs. This keyword is necessary only if garbage collection for Heaprefs was turned off using the DISABLE keyword. If Heaprefs is not supplied, automatic garbage collection is re-enabled for all heap variables.

IS_ENABLED

Set this keyword to a named variable which will contain the value 1 if garbage collection is enabled for the heap variable, or 0 if garbage collection is disabled. If Heaprefs is an array, the variable will contain an array of 1s or 0s.

If Heaprefs is not supplied, the variable value reflects the state of garbage collection for all heap variables (1 if automatic garbage collection is enabled, 0 if garbage collection is disabled).

Version History

8.0	Introduced