kotlin-stdlib / kotlin.native.runtime / GC

GC

Native

1.9

@NativeRuntimeApi object GC
(source)

Note: this API is unstable and may change in any release.

Kotlin/Native uses tracing garbage collector (GC) that is executed periodically to collect objects that are not reachable from the "roots", like local and global variables. See documentation to learn more about Kotlin/Native memory management.

This object provides a set of functions and properties that allows to tune garbage collector.

Legacy memory manager

Kotlin/Native relies upon reference counting for object management, however it could not collect cyclical garbage, so we perform periodic garbage collection. This may slow down application, so this interface provides control over how garbage collector activates and runs. Garbage collector can be in one of the following states:

running
suspended (so cycle candidates are collected, but GC is not performed until resume)
stopped (all cyclical garbage is hopelessly lost) Immediately after startup GC is in running state. Depending on application needs it may select to suspend GC for certain phases of its lifetime, and resume it later on, or just completely turn it off, if GC pauses are less desirable than cyclical garbage leaks.

Properties

Native

1.3

autotune

If true update targetHeapBytes after each collection.

var autotune: Boolean

Native

1.3

collectCyclesThreshold

Deprecated and unused.

var collectCyclesThreshold: Long

Native

1.3

cyclicCollectorEnabled

Deprecated and unused.

var cyclicCollectorEnabled: Boolean

Native

1.3

heapTriggerCoefficient

The GC is scheduled when Kotlin heap overflows heapTriggerCoefficient * targetHeapBytes.

var heapTriggerCoefficient: Double

Native

1.3

lastGCInfo

Returns statistics of the last finished garbage collection run. This information is supposed to be used for testing and debugging purposes only

val lastGCInfo: GCInfo?

Native

1.3

maxHeapBytes

The maximum value for targetHeapBytes. Only used if autotune is true. See targetHeapBytes for more details.

var maxHeapBytes: Long

Native

1.3

minHeapBytes

The minimum value for targetHeapBytes Only used if autotune is true. See targetHeapBytes for more details.

var minHeapBytes: Long

Native

1.3

pauseOnTargetHeapOverflow

If true, the GC will pause Kotlin threads when Kotlin heap overflows targetHeapBytes and will resume them only after current GC is done.

var pauseOnTargetHeapOverflow: Boolean

Native

1.3

regularGCInterval

When Kotlin code is not allocating enough to trigger GC, the GC scheduler uses timer to drive collection. Timer-triggered collection will happen roughly in regularGCInterval .. 2 * regularGCInterval since any previous collection.

var regularGCInterval: Duration

Native

1.3

targetHeapBytes

Total amount of heap available for Kotlin objects. The GC tries to schedule execution so that Kotlin heap doesn't overflow this heap. Automatically adjusts when autotune is true: after each collection the targetHeapBytes is set to heapBytes / targetHeapUtilization and capped between minHeapBytes and maxHeapBytes, where heapBytes is heap usage after the garbage is collected. Note, that if after a collection heapBytes > targetHeapBytes (which may happen if autotune is false, or maxHeapBytes is set too low), the next collection will be triggered almost immediately.

var targetHeapBytes: Long

Native

1.3