Module Gc
Author: Christian.Queinnec@lip6.fr

## Module `Gc`

The `Gc` module lets one obtain statistics about the heap and gives control over its evolution as well as allowing the activation of various garbage collector phases. Two concrete record types are defined: stat and control. The fields of type control are modifiable; whereas those of stat are not. The latter simply reflect the state of the heap at a given moment.
The fields of a stat mainly contain counters indicating:

- the number of garbage collections: `minor_collections`, `major_collections` and `compactions`;
- the number of words allocated and transfered since the beginning of the program: `minor_words`, `promoted_words`, and `major_words`.

The fields of the record control are:

- `minor_heap_size`, which defines the size of the zone allotted to the younger generation;
- `major_heap_increment`, which defines the increment applied to the growth of the region for the older generation;
- `space_overhead`, which defines the percentage of the memory used beyond which a major garbage collection is begun (the default value is 42);
- `max_overhead`, which defines the connection between free memory and occupied memory after which compactification is activated. A value of 0 causes a systematic compactification after every major garbage collection. The maximal value of 1000000 inhibits compactification.
- `verbose` is an integer parameter governing the tracing of the activities of the garbage collector.

Functions manipulating the types stat and control are given in figure 9.13.

> `stat` | unit -> stat
> `print_stat` | out_channel -> unit
> `get` | unit ® control
> `set` | control -> unit

> Figure 9.13: Control and statistical functions for the heap.

The following functions, of type unit -> unit, force the execution of one or more stages of the Objective CAML garbage collector: `minor` (stage 1), `major` (stages 1 and 2), `full_major` (stages 1, 2 and 3) and `compact` (stages 1, 2, 3 and 4).

#### Examples

Here is what the `Gc.stat` call shows:

    # Gc.stat();;
    - : Gc.stat =
    {Gc.minor_words=549290; Gc.promoted_words=60620; Gc.major_words=204615;
     Gc.minor_collections=17; Gc.major_collections=2; Gc.heap_words=190464;
     Gc.heap_chunks=3; Gc.live_words=52727; Gc.live_blocks=12959;
     Gc.free_words=31155; Gc.free_blocks=84; Gc.largest_free=17899;
     Gc.fragments=3; Gc.compactions=0}

We see the number of executions of each phase: minor garbage collection, major garbage collection, compaction, as well as the number of words handled by the different memory spaces. Calling `compact` forces the four stages of the garbage collector, causing the heap statistics to be modified (see the call of `Gc.stat`).

    # Gc.compact();;
    - : unit = ()
    # Gc.stat();;
    - : Gc.stat =
    {Gc.minor_words=555758; Gc.promoted_words=61651; Gc.major_words=205646;
     Gc.minor_collections=18; Gc.major_collections=4; Gc.heap_words=190464;
     Gc.heap_chunks=3; Gc.live_words=130637; Gc.live_blocks=30770;
     Gc.free_words=59827; Gc.free_blocks=1; Gc.largest_free=59827;
     Gc.fragments=0; Gc.compactions=1}

The fields `GC.minor_collections` and `compactions` are incremented by 1, whereas the field `Gc.major_collections` is incremented by 2. All of the fields of type GC.control are modifiable. For them to be taken into account, we must use the function `Gc.set`, which takes a value of type control and modifies the behavior of the garbage collector.
For example, the field `verbose` may take a value from 0 to 127, controlling 7 different indicators.

    # c.Gc.verbose <- 31;;
    Characters 1-2:
    This expression has type int * int but is here used with type Gc.control
    # Gc.set c;;
    Characters 7-8:
    This expression has type int * int but is here used with type Gc.control
    # Gc.compact();;
    - : unit = ()

which prints:

    <>Starting new major GC cycle
    allocated_words = 329
    extra_heap_memory = 0u
    amount of work to do = 3285u
    Marking 1274 words
    !Starting new major GC cycle
    Compacting heap...
    done.

The different phases of the garbage collector are indicated as well as the number of objects processed.