package async_kernel

  1. Overview
  2. Docs
package async_kernel
Legend:
Library
Module
Module type
Parameter
Class
Class type

Async's analog of Core.Gc.

We remove the Expert module, which has functions that are superseded by Async-friendly functions below.

include module type of Core.Gc with module Expert := Core.Gc.Expert
module Stat = Core.Gc.Stat
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 = Core.Gc.Control
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 : Stdlib.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 = Core.Gc.Allocation_policy

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 = Core.Gc.For_testing
module Stable = Core.Gc.Stable
val add_finalizer : 'a Core.Heap_block.t -> ('a Core.Heap_block.t -> unit) -> unit

add_finalizer b f ensures that f runs after b becomes unreachable. f b will run in its own Async job. If f raises, the unhandled exception will be raised to the monitor that called add_finalizer b f.

The OCaml runtime only supports finalizers on heap blocks, hence add_finalizer requires b : _ Heap_block.t.

The runtime essentially maintains a set of finalizer pairs:

'a Heap_block.t * ('a Heap_block.t -> unit)

Each call to add_finalizer adds a new pair to the set. It is allowed for many pairs to have the same heap block, the same function, or both. Each pair is a distinct element of the set.

After a garbage collection determines that a heap block b is unreachable, it removes from the set of finalizers all finalizer pairs (b, f) whose block is b, and then and runs f b for all such pairs. Thus, a finalizer registered with add_finalizer will run at most once.

In a finalizer pair (b, f), it is a mistake for the closure of f to reference (directly or indirectly) b -- f should only access b via its argument. Referring to b in any other way will cause b to be kept alive forever, since f itself is a root of garbage collection, and can itself only be collected after the pair (b, f) is removed from the set of finalizers.

The f function can use all features of OCaml and Async, since it runs as an ordinary Async job. f can even make b reachable again. It can even call add_finalizer on b or other values to register other finalizer functions.

val add_finalizer_exn : 'a -> ('a -> unit) -> unit

add_finalizer_exn b f is like add_finalizer, but will raise if b is not a heap block.

val add_finalizer_last : 'a Core.Heap_block.t -> (unit -> unit) -> unit

Same as add_finalizer except that the function is not called until the value has become unreachable for the last time. This means that the finalization function does not receive the value as an argument. Every weak pointer and ephemeron that contained this value as key or data is unset before running the finalization function.

val add_finalizer_last_exn : 'a -> (unit -> unit) -> unit
module Alarm : sig ... end

A GC alarm calls a user function after the end of each major GC cycle.

OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct