Module Core.Gc

This is a wrapper around INRIA's standard Gc module. Provides memory management control and statistics, and finalized values.

module Stat : sig ... end
type stat = Stat.t

The memory management counters are returned in a stat record.

The total amount of memory allocated by the program since it was started is (in words) minor_words + major_words - promoted_words. Multiply by the word size (4 on a 32-bit machine, 8 on a 64-bit machine) to get the number of bytes.

module Control : sig ... end
type control = Control.t

The GC parameters are given as a control record. Note that these parameters can also be initialised by setting the OCAMLRUNPARAM environment variable. See the documentation of ocamlrun.

val stat : Base.Unit.t -> stat

Return the current values of the memory management counters in a stat record that represent the program's total memory stats.

OCaml 4 runtime: This function examines every heap block to get the statistics.

OCaml 5 runtime: This function causes a full major collection.

val stat_size : Base.Unit.t -> Base.Int.t

Creating a Stat.t can allocate on the minor heap. Return the expected number of words allocated. *

val quick_stat : Base.Unit.t -> stat

Same as stat except that live_words, live_blocks, free_words, free_blocks, largest_free, and fragments are set to 0.

OCaml 4 runtime: This function is much faster than stat because it does not need to go through the heap.

OCaml 5 runtime: Due to per-domain buffers it may only represent the state of the program's total memory usage since the last minor collection. As a result returned values are representing an approximation of the gc statistics.

This function is much faster than stat because it does not need to trigger a full major collection.

Return (minor_words, promoted_words, major_words) (on the OCaml 5 runtime, for the current domain or potentially previous domains). This function is as fast as quick_stat.

Note: on the OCaml 5 runtime, quick_stat and counters might not return the same value, even if there's only a single domain. If there's only one domain running then counters returns the exact number of minor words, promoted words and major words allocated so far.

On 32-bit machines the ints returned by the following functions may overflow.

val minor_words : Base.Unit.t -> Base.Int.t

Number of words allocated in the minor heap by this domain (or, on the OCaml 5 runtime, potentially previous domains). This number is accurate in byte-code programs, but only an approximation in programs compiled to native code.

Note that minor_words does not allocate, but we do not annotate it as noalloc because we want the compiler to save the value of the allocation pointer register (%r15 on x86-64) to the global variable caml_young_ptr before the C stub tries to read its value.

val major_words : Base.Unit.t -> Base.Int.t
val promoted_words : Base.Unit.t -> Base.Int.t
val minor_collections : Base.Unit.t -> Base.Int.t
val major_collections : Base.Unit.t -> Base.Int.t
val compactions : Base.Unit.t -> Base.Int.t
val heap_words : Base.Unit.t -> Base.Int.t
val heap_chunks : Base.Unit.t -> Base.Int.t
val top_heap_words : Base.Unit.t -> Base.Int.t
val major_plus_minor_words : Base.Unit.t -> Base.Int.t

This function returns major_words () + minor_words (). It exists purely for speed (one call into C rather than two). Like major_words and minor_words, major_plus_minor_words avoids allocating a stat record or a float, and may overflow on 32-bit machines.

This function is not marked [@@noalloc] to ensure that the allocation pointer is up-to-date when the minor-heap measurement is made.

val allocated_words : Base.Unit.t -> Base.Int.t

This function returns major_words () - promoted_words () + minor_words (), as fast as possible. As major_plus_minor_words, we avoid allocating but cannot be marked @@noalloc yet. It may overflow in 32-bit mode.

val get : Base.Unit.t -> control

Return the current values of the GC parameters in a control record.

val set : control -> Base.Unit.t

set r changes the GC parameters according to the control record r. The normal usage is: Gc.set { (Gc.get()) with Gc.Control.verbose = 0x00d }

val minor : Base.Unit.t -> Base.Unit.t

Trigger a minor collection.

val major_slice : Base.Int.t -> Base.Int.t

Do a minor collection and a slice of major collection. The argument is the size of the slice, 0 to use the automatically-computed slice size. In all cases, the result is the computed slice size.

val major : Base.Unit.t -> Base.Unit.t

Do a minor collection and finish the current major collection cycle.

val full_major : Base.Unit.t -> Base.Unit.t

Do a minor collection, finish the current major collection cycle, and perform a complete new cycle. This will collect all currently unreachable blocks.

val compact : Base.Unit.t -> Base.Unit.t

Perform a full major collection and compact the heap. Note that heap compaction is a lengthy operation.

val print_stat : out_channel -> Base.Unit.t

Print the current values of the memory management counters (in human-readable form) into the channel argument.

val allocated_bytes : Base.Unit.t -> Base.Float.t

Return the total number of bytes allocated since the program was started. It is returned as a float to avoid overflow problems with int on 32-bit machines.

val keep_alive : _ -> Base.Unit.t

keep_alive a ensures that a is live at the point where keep_alive a is called. It is like ignore a, except that the compiler won't be able to simplify it and potentially collect a too soon.

module Allocation_policy : sig ... end

The policy used for allocating in the heap.

val tune : ?logger:(Base.String.t -> Base.Unit.t) -> ?minor_heap_size:Base.Int.t -> ?major_heap_increment:Base.Int.t -> ?space_overhead:Base.Int.t -> ?verbose:Base.Int.t -> ?max_overhead:Base.Int.t -> ?stack_limit:Base.Int.t -> ?allocation_policy:Allocation_policy.t -> ?window_size:Base.Int.t -> ?custom_major_ratio:Base.Int.t -> ?custom_minor_ratio:Base.Int.t -> ?custom_minor_max_size:Base.Int.t -> Base.Unit.t -> Base.Unit.t

Adjust the specified GC parameters.

val disable_compaction : ?logger:(Base.String.t -> Base.Unit.t) -> allocation_policy:[ `Don't_change | `Set_to of Allocation_policy.t ] -> Base.Unit.t -> Base.Unit.t
module For_testing : sig ... end
module Expert : sig ... end

The Expert module contains functions that novice users should not use, due to their complexity.

module Stable : sig ... end