.TH "Gc" 3o source: 2016-12-21 OCamldoc "OCaml library"
.SH NAME
Gc \- Memory management control and statistics; finalised values.
.SH Module
Module   Gc
.SH Documentation
.sp
Module
.BI "Gc"
 : 
.B sig  end

.sp
Memory management control and statistics; finalised values\&.

.sp

.sp
.sp
.I type stat 
= {
 minor_words : 
.B float
;  (* Number of words allocated in the minor heap since
the program was started\&.  This number is accurate in
byte\-code programs, but only an approximation in programs
compiled to native code\&.
 *) 
 promoted_words : 
.B float
;  (* Number of words allocated in the minor heap that
survived a minor collection and were moved to the major heap
since the program was started\&.
 *) 
 major_words : 
.B float
;  (* Number of words allocated in the major heap, including
the promoted words, since the program was started\&.
 *) 
 minor_collections : 
.B int
;  (* Number of minor collections since the program was started\&.
 *) 
 major_collections : 
.B int
;  (* Number of major collection cycles completed since the program
was started\&.
 *) 
 heap_words : 
.B int
;  (* Total size of the major heap, in words\&.
 *) 
 heap_chunks : 
.B int
;  (* Number of contiguous pieces of memory that make up the major heap\&.
 *) 
 live_words : 
.B int
;  (* Number of words of live data in the major heap, including the header
words\&.
 *) 
 live_blocks : 
.B int
;  (* Number of live blocks in the major heap\&.
 *) 
 free_words : 
.B int
;  (* Number of words in the free list\&.
 *) 
 free_blocks : 
.B int
;  (* Number of blocks in the free list\&.
 *) 
 largest_free : 
.B int
;  (* Size (in words) of the largest block in the free list\&.
 *) 
 fragments : 
.B int
;  (* Number of wasted words due to fragmentation\&.  These are
1\-words free blocks placed between two live blocks\&.  They
are not available for allocation\&.
 *) 
 compactions : 
.B int
;  (* Number of heap compactions since the program was started\&.
 *) 
 top_heap_words : 
.B int
;  (* Maximum size reached by the major heap, in words\&.
 *) 
 stack_size : 
.B int
;  (* Current size of the stack, in words\&.

.sp
.B "Since"
3.12.0
 *) 
 }

.sp
The memory management counters are returned in a 
.B stat
record\&.
.sp
The total amount of memory allocated by the program since it was started
is (in words) 
.B 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\&.

.sp
.I type control 
= {

.B mutable 
minor_heap_size : 
.B int
;  (* The size (in words) of the minor heap\&.  Changing
this parameter will trigger a minor collection\&.  Default: 256k\&.
 *) 

.B mutable 
major_heap_increment : 
.B int
;  (* How much to add to the major heap when increasing it\&. If this
number is less than or equal to 1000, it is a percentage of
the current heap size (i\&.e\&. setting it to 100 will double the heap
size at each increase)\&. If it is more than 1000, it is a fixed
number of words that will be added to the heap\&. Default: 15\&.
 *) 

.B mutable 
space_overhead : 
.B int
;  (* The major GC speed is computed from this parameter\&.
This is the memory that will be "wasted" because the GC does not
immediatly collect unreachable blocks\&.  It is expressed as a
percentage of the memory used for live data\&.
The GC will work more (use more CPU time and collect
blocks more eagerly) if 
.B space_overhead
is smaller\&.
Default: 80\&.
 *) 

.B mutable 
verbose : 
.B int
;  (* This value controls the GC messages on standard error output\&.
It is a sum of some of the following flags, to print messages
on the corresponding events:
.sp
\-
.B 0x001
Start of major GC cycle\&.
.sp
\-
.B 0x002
Minor collection and major GC slice\&.
.sp
\-
.B 0x004
Growing and shrinking of the heap\&.
.sp
\-
.B 0x008
Resizing of stacks and memory manager tables\&.
.sp
\-
.B 0x010
Heap compaction\&.
.sp
\-
.B 0x020
Change of GC parameters\&.
.sp
\-
.B 0x040
Computation of major GC slice size\&.
.sp
\-
.B 0x080
Calling of finalisation functions\&.
.sp
\-
.B 0x100
Bytecode executable and shared library search at start\-up\&.
.sp
\-
.B 0x200
Computation of compaction\-triggering condition\&.
Default: 0\&.

 *) 

.B mutable 
max_overhead : 
.B int
;  (* Heap compaction is triggered when the estimated amount
of "wasted" memory is more than 
.B max_overhead
percent of the
amount of live data\&.  If 
.B max_overhead
is set to 0, heap
compaction is triggered at the end of each major GC cycle
(this setting is intended for testing purposes only)\&.
If 
.B max_overhead >= 1000000
, compaction is never triggered\&.
If compaction is permanently disabled, it is strongly suggested
to set 
.B allocation_policy
to 1\&.
Default: 500\&.
 *) 

.B mutable 
stack_limit : 
.B int
;  (* The maximum size of the stack (in words)\&.  This is only
relevant to the byte\-code runtime, as the native code runtime
uses the operating system\&'s stack\&.  Default: 1024k\&.
 *) 

.B mutable 
allocation_policy : 
.B int
;  (* The policy used for allocating in the heap\&.  Possible
values are 0 and 1\&.  0 is the next\-fit policy, which is
quite fast but can result in fragmentation\&.  1 is the
first\-fit policy, which can be slower in some cases but
can be better for programs with fragmentation problems\&.
Default: 0\&.

.sp
.B "Since"
3.11.0
 *) 
 }

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

.sp

.I val stat 
: 
.B unit -> stat
.sp
Return the current values of the memory management counters in a
.B stat
record\&.  This function examines every heap block to get the
statistics\&.

.sp

.I val quick_stat 
: 
.B unit -> stat
.sp
Same as 
.B stat
except that 
.B live_words
, 
.B live_blocks
, 
.B free_words
,
.B free_blocks
, 
.B largest_free
, and 
.B fragments
are set to 0\&.  This
function is much faster than 
.B stat
because it does not need to go
through the heap\&.

.sp

.I val counters 
: 
.B unit -> float * float * float
.sp
Return 
.B (minor_words, promoted_words, major_words)
\&.  This function
is as fast as 
.B quick_stat
\&.

.sp

.I val get 
: 
.B unit -> control
.sp
Return the current values of the GC parameters in a 
.B control
record\&.

.sp

.I val set 
: 
.B control -> unit
.sp

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


.sp

.I val minor 
: 
.B unit -> unit
.sp
Trigger a minor collection\&.

.sp

.I val major_slice 
: 
.B int -> int
.sp
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\&.

.sp

.I val major 
: 
.B unit -> unit
.sp
Do a minor collection and finish the current major collection cycle\&.

.sp

.I val full_major 
: 
.B unit -> unit
.sp
Do a minor collection, finish the current major collection cycle,
and perform a complete new cycle\&.  This will collect all currently
unreachable blocks\&.

.sp

.I val compact 
: 
.B unit -> unit
.sp
Perform a full major collection and compact the heap\&.  Note that heap
compaction is a lengthy operation\&.

.sp

.I val print_stat 
: 
.B Pervasives.out_channel -> unit
.sp
Print the current values of the memory management counters (in
human\-readable form) into the channel argument\&.

.sp

.I val allocated_bytes 
: 
.B unit -> float
.sp
Return the total number of bytes allocated since the program was
started\&.  It is returned as a 
.B float
to avoid overflow problems
with 
.B int
on 32\-bit machines\&.

.sp

.I val finalise 
: 
.B ('a -> unit) -> 'a -> unit
.sp

.B finalise f v
registers 
.B f
as a finalisation function for 
.B v
\&.
.B v
must be heap\-allocated\&.  
.B f
will be called with 
.B v
as
argument at some point between the first time 
.B v
becomes unreachable
and the time 
.B v
is collected by the GC\&.  Several functions can
be registered for the same value, or even several instances of the
same function\&.  Each instance will be called once (or never,
if the program terminates before 
.B v
becomes unreachable)\&.
.sp
The GC will call the finalisation functions in the order of
deallocation\&.  When several values become unreachable at the
same time (i\&.e\&. during the same GC cycle), the finalisation
functions will be called in the reverse order of the corresponding
calls to 
.B finalise
\&.  If 
.B finalise
is called in the same order
as the values are allocated, that means each value is finalised
before the values it depends upon\&.  Of course, this becomes
false if additional dependencies are introduced by assignments\&.
.sp
In the presence of multiple OCaml threads it should be assumed that
any particular finaliser may be executed in any of the threads\&.
.sp
Anything reachable from the closure of finalisation functions
is considered reachable, so the following code will not work
as expected:
.sp
\-
.B  let v = \&.\&.\&. in Gc\&.finalise (fun x \-> \&.\&.\&. v \&.\&.\&.) v 

Instead you should make sure that 
.B v
is not in the closure of
the finalisation function by writing:
.sp
\-
.B  let f = fun x \-> \&.\&.\&. ;; let v = \&.\&.\&. in Gc\&.finalise f v 

The 
.B f
function can use all features of OCaml, including
assignments that make the value reachable again\&.  It can also
loop forever (in this case, the other
finalisation functions will not be called during the execution of f,
unless it calls 
.B finalise_release
)\&.
It can call 
.B finalise
on 
.B v
or other values to register other
functions or even itself\&.  It can raise an exception; in this case
the exception will interrupt whatever the program was doing when
the function was called\&.
.sp

.B finalise
will raise 
.B Invalid_argument
if 
.B v
is not
heap\-allocated\&.  Some examples of values that are not
heap\-allocated are integers, constant constructors, booleans,
the empty array, the empty list, the unit value\&.  The exact list
of what is heap\-allocated or not is implementation\-dependent\&.
Some constant values can be heap\-allocated but never deallocated
during the lifetime of the program, for example a list of integer
constants; this is also implementation\-dependent\&.
You should also be aware that compiler optimisations may duplicate
some immutable values, for example floating\-point numbers when
stored into arrays, so they can be finalised and collected while
another copy is still in use by the program\&.
.sp
The results of calling 
.B String\&.make
, 
.B Bytes\&.make
, 
.B Bytes\&.create
,
.B Array\&.make
, and 
.B Pervasives\&.ref
are guaranteed to be
heap\-allocated and non\-constant except when the length argument is 
.B 0
\&.

.sp

.I val finalise_release 
: 
.B unit -> unit
.sp
A finalisation function may call 
.B finalise_release
to tell the
GC that it can launch the next finalisation function without waiting
for the current one to return\&.

.sp
.I type alarm 

.sp
An alarm is a piece of data that calls a user function at the end of
each major GC cycle\&.  The following functions are provided to create
and delete alarms\&.

.sp

.I val create_alarm 
: 
.B (unit -> unit) -> alarm
.sp

.B create_alarm f
will arrange for 
.B f
to be called at the end of each
major GC cycle, starting with the current cycle or the next one\&.
A value of type 
.B alarm
is returned that you can
use to call 
.B delete_alarm
\&.

.sp

.I val delete_alarm 
: 
.B alarm -> unit
.sp

.B delete_alarm a
will stop the calls to the function associated
to 
.B a
\&.  Calling 
.B delete_alarm a
again has no effect\&.

.sp