Module Async_kernel__.Async_gc
We remove the Expert
module, which has functions that are superseded by Async-friendly functions below.
include module type of Core_kernel.Gc with module Gc.Expert := Core_kernel.Gc.Expert
module Stat = Core_kernel.Gc.Stat
type stat
= Stat.t
module Control = Core_kernel.Gc.Control
type control
= Control.t
val stat : Core_kernel__.Import.unit -> stat
Return the current values of the memory management counters in a
stat
record. This function examines every heap block to get the statistics.
val quick_stat : Core_kernel__.Import.unit -> stat
Same as
stat
except thatlive_words
,live_blocks
,free_words
,free_blocks
,largest_free
, andfragments
are set to 0. This function is much faster thanstat
because it does not need to go through the heap.
val counters : Core_kernel__.Import.unit -> Core_kernel__.Import.float * Core_kernel__.Import.float * Core_kernel__.Import.float
Return
(minor_words, promoted_words, major_words)
. This function is as fast atquick_stat
.
val minor_words : Core_kernel__.Import.unit -> Core_kernel__.Import.int
The following functions return the same as
(Gc.quick_stat ()).Stat.f
, avoiding any allocation (of thestat
record or a float). On 32-bit machines theint
may overflow.Note that
minor_words
does not allocate, but we do not annotate it asnoalloc
because we want the compiler to save the value of the allocation pointer register (%r15 on x86-64) to the global variablecaml_young_ptr
before the C stub tries to read its value.
val major_words : Core_kernel__.Import.unit -> Core_kernel__.Import.int
val promoted_words : Core_kernel__.Import.unit -> Core_kernel__.Import.int
val minor_collections : Core_kernel__.Import.unit -> Core_kernel__.Import.int
val major_collections : Core_kernel__.Import.unit -> Core_kernel__.Import.int
val heap_words : Core_kernel__.Import.unit -> Core_kernel__.Import.int
val heap_chunks : Core_kernel__.Import.unit -> Core_kernel__.Import.int
val compactions : Core_kernel__.Import.unit -> Core_kernel__.Import.int
val top_heap_words : Core_kernel__.Import.unit -> Core_kernel__.Import.int
val major_plus_minor_words : Core_kernel__.Import.unit -> Core_kernel__.Import.int
This function returns
major_words () + minor_words ()
. It exists purely for speed (one call into C rather than two). Likemajor_words
andminor_words
,major_plus_minor_words
avoids allocating astat
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 : Core_kernel__.Import.unit -> Core_kernel__.Import.int
This function returns
major_words () - promoted_words () + minor_words ()
, as fast as possible. Asmajor_plus_minor_words
, we avoid allocating but cannot be marked@@noalloc
yet. It may overflow in 32-bit mode.
val get : Core_kernel__.Import.unit -> control
Return the current values of the GC parameters in a
control
record.
val set : control -> Core_kernel__.Import.unit
set r
changes the GC parameters according to thecontrol
recordr
. The normal usage is:Gc.set { (Gc.get()) with Gc.Control.verbose = 0x00d }
val minor : Core_kernel__.Import.unit -> Core_kernel__.Import.unit
Trigger a minor collection.
val major_slice : Core_kernel__.Import.int -> Core_kernel__.Import.int
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 : Core_kernel__.Import.unit -> Core_kernel__.Import.unit
Do a minor collection and finish the current major collection cycle.
val full_major : Core_kernel__.Import.unit -> Core_kernel__.Import.unit
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 : Core_kernel__.Import.unit -> Core_kernel__.Import.unit
Perform a full major collection and compact the heap. Note that heap compaction is a lengthy operation.
val print_stat : Stdlib.out_channel -> Core_kernel__.Import.unit
Print the current values of the memory management counters (in human-readable form) into the channel argument.
val allocated_bytes : Core_kernel__.Import.unit -> Core_kernel__.Import.float
Return the total number of bytes allocated since the program was started. It is returned as a
float
to avoid overflow problems withint
on 32-bit machines.
val keep_alive : _ -> Core_kernel__.Import.unit
keep_alive a
ensures thata
is live at the point wherekeep_alive a
is called. It is likeignore a
, except that the compiler won't be able to simplify it and potentially collecta
too soon.
module Allocation_policy = Core_kernel.Gc.Allocation_policy
The policy used for allocating in the heap.
val tune : ?logger:(Core_kernel__.Import.string -> Core_kernel__.Import.unit) -> ?minor_heap_size:Core_kernel__.Import.int -> ?major_heap_increment:Core_kernel__.Import.int -> ?space_overhead:Core_kernel__.Import.int -> ?verbose:Core_kernel__.Import.int -> ?max_overhead:Core_kernel__.Import.int -> ?stack_limit:Core_kernel__.Import.int -> ?allocation_policy:Allocation_policy.t -> ?window_size:Core_kernel__.Import.int -> ?custom_major_ratio:Core_kernel__.Import.int -> ?custom_minor_ratio:Core_kernel__.Import.int -> ?custom_minor_max_size:Core_kernel__.Import.int -> Core_kernel__.Import.unit -> Core_kernel__.Import.unit
Adjust the specified GC parameters.
val disable_compaction : ?logger:(Core_kernel__.Import.string -> Core_kernel__.Import.unit) -> allocation_policy:[ `Don't_change | `Set_to of Allocation_policy.t ] -> Core_kernel__.Import.unit -> Core_kernel__.Import.unit
module For_testing = Core_kernel.Gc.For_testing
module Expert = Core_kernel.Gc.Expert
The
Expert
module contains functions that novice users should not use, due to their complexity.
module Stable = Core_kernel.Gc.Stable
val add_finalizer : 'a Core_kernel.Heap_block.t -> ('a Core_kernel.Heap_block.t -> unit) -> unit
add_finalizer b f
ensures thatf
runs afterb
becomes unreachable.f b
will run in its own Async job. Iff
raises, the unhandled exception will be raised to the monitor that calledadd_finalizer b f
.The OCaml runtime only supports finalizers on heap blocks, hence
add_finalizer
requiresb : _ 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 isb
, and then and runsf b
for all such pairs. Thus, a finalizer registered withadd_finalizer
will run at most once.In a finalizer pair
(b, f)
, it is a mistake for the closure off
to reference (directly or indirectly)b
--f
should only accessb
via its argument. Referring tob
in any other way will causeb
to be kept alive forever, sincef
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 makeb
reachable again. It can even calladd_finalizer
onb
or other values to register other finalizer functions.
val add_finalizer_exn : 'a -> ('a -> unit) -> unit
add_finalizer_exn b f
is likeadd_finalizer
, but will raise ifb
is not a heap block.
val add_finalizer_last : 'a Core_kernel.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.
module Alarm : sig ... end
A GC alarm calls a user function after the end of each major GC cycle.