Up

Module Async_gc

Async's analog of Core_kernel.Std.Gc.

Signature

include module type of Core_kernel.Std.Gc with module Expert := Core_kernel.Std.Gc.Expert
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.

external stat : unit -> stat = "caml_gc_stat"

Return the current values of the memory management counters in a stat record. This function examines every heap block to get the statistics.

external quick_stat : unit -> stat = "caml_gc_quick_stat"

Same as stat except that live_words, live_blocks, free_words, free_blocks, largest_free, and fragments are set to 0. This function is much faster than stat because it does not need to go through the heap.

external counters : unit -> float * float * float = "caml_gc_counters"

Return (minor_words, promoted_words, major_words). This function is as fast at quick_stat.

external minor_words : unit -> int = "core_kernel_gc_minor_words"

The following functions return the same as (Gc.quick_stat ()).Stat.f, avoiding any allocation (of the stat record or a float). On 32-bit machines the int may overflow.

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.

external major_words : unit -> int = "core_kernel_gc_major_words" "noalloc"
external promoted_words : unit -> int = "core_kernel_gc_promoted_words" "noalloc"
external minor_collections : unit -> int = "core_kernel_gc_minor_collections" "noalloc"
external major_collections : unit -> int = "core_kernel_gc_major_collections" "noalloc"
external heap_words : unit -> int = "core_kernel_gc_heap_words" "noalloc"
external heap_chunks : unit -> int = "core_kernel_gc_heap_chunks" "noalloc"
external compactions : unit -> int = "core_kernel_gc_compactions" "noalloc"
external top_heap_words : unit -> int = "core_kernel_gc_top_heap_words" "noalloc"
external major_plus_minor_words : unit -> int = "core_kernel_gc_major_plus_minor_words"

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.

external get : unit -> control = "caml_gc_get"

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

external set : control -> unit = "caml_gc_set"

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 }

external minor : unit -> unit = "caml_gc_minor"

Trigger a minor collection.

external major_slice : int -> int = "caml_gc_major_slice"

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.

external major : unit -> unit = "caml_gc_major"

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

external full_major : unit -> unit = "caml_gc_full_major"

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

external compact : unit -> unit = "caml_gc_compaction"

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

val print_stat : Pervasives.out_channel -> unit

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

val allocated_bytes : unit -> float

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 : _ -> unit
val tune : ?logger:(string -> unit) -> ?minor_heap_size:int -> ?major_heap_increment:int -> ?space_overhead:int -> ?verbose:int -> ?max_overhead:int -> ?stack_limit:int -> ?allocation_policy:int -> unit -> unit

Adjust the specified GC parameters.

module Allocation_policy : sig .. end
The policy used for allocating in the heap.
val disable_compaction : ?logger:(string -> unit) -> allocation_policy:[
| `Don't_change
| `Set_to of Allocation_policy.t
] -> unit -> unit
module Expert : sig .. end
The Expert module contains functions that novice users should not use, due to their complexity.
val add_finalizer : 'a Core_kernel.Std.Heap_block.t -> ('a Core_kernel.Std.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. add_finalizer_exn b f is like add_finalizer, but will raise if b is not a heap block.

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 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
module Alarm : sig .. end
A GC alarm calls a user function after the end of each major GC cycle.