1Gc(3)                            OCaml library                           Gc(3)
2
3
4

NAME

6       Gc - Memory management control and statistics; finalised values.
7

Module

9       Module   Gc
10

Documentation

12       Module Gc
13        : sig end
14
15
16       Memory management control and statistics; finalised values.
17
18
19
20
21
22
23       type stat = {
24        minor_words  : float ;  (* Number of words allocated in the minor heap
25       since the program was started.  This number is  accurate  in  byte-code
26       programs,  but  only  an  approximation  in programs compiled to native
27       code. *)
28        promoted_words : float ;  (* Number of words allocated  in  the  minor
29       heap  that survived a minor collection and were moved to the major heap
30       since the program was started. *)
31        major_words : float ;  (* Number of words allocated in the major heap,
32       including the promoted words, since the program was started. *)
33        minor_collections  :  int  ;  (* Number of minor collections since the
34       program was started. *)
35        major_collections : int ;  (* Number of major collection  cycles  com‐
36       pleted since the program was started. *)
37        heap_words : int ;  (* Total size of the major heap, in words. *)
38        heap_chunks  :  int  ;   (* Number of contiguous pieces of memory that
39       make up the major heap. *)
40        live_words : int ;  (* Number of words of live data in the major heap,
41       including the header words. *)
42        live_blocks : int ;  (* Number of live blocks in the major heap. *)
43        free_words : int ;  (* Number of words in the free list. *)
44        free_blocks : int ;  (* Number of blocks in the free list. *)
45        largest_free  :  int ;  (* Size (in words) of the largest block in the
46       free list. *)
47        fragments : int ;  (* Number of wasted  words  due  to  fragmentation.
48       These are 1-words free blocks placed between two live blocks.  They are
49       not available for allocation. *)
50        compactions : int ;  (* Number of heap compactions since  the  program
51       was started. *)
52        top_heap_words  : int ;  (* Maximum size reached by the major heap, in
53       words. *)
54        }
55
56
57       The memory management counters are returned in a stat record.
58
59       The total amount of memory  allocated  by  the  program  since  it  was
60       started  is  (in  words)  minor_words  + major_words - promoted_words .
61       Multiply by the word size (4  on  a  32-bit  machine,  8  on  a  64-bit
62       machine) to get the number of bytes.
63
64
65
66       type control = {
67
68       mutable  minor_heap_size  :  int ;  (* The size (in words) of the minor
69       heap.   Changing  this  parameter  will  trigger  a  minor  collection.
70       Default: 32k. *)
71
72       mutable major_heap_increment : int ;  (* The minimum number of words to
73       add to the major heap when increasing it.  Default: 124k. *)
74
75       mutable space_overhead : int ;  (* The major GC speed is computed  from
76       this  parameter.   This is the memory that will be "wasted" because the
77       GC does not immediatly collect unreachable blocks.  It is expressed  as
78       a  percentage  of the memory used for live data.  The GC will work more
79       (use more CPU time and collect blocks more eagerly)  if  space_overhead
80       is smaller.  Default: 80. *)
81
82       mutable  verbose  :  int  ;   (* This value controls the GC messages on
83       standard error output.  It is a sum of some of the following flags,  to
84       print messages on the corresponding events:
85
86       - 0x001 Start of major GC cycle.
87
88       - 0x002 Minor collection and major GC slice.
89
90       - 0x004 Growing and shrinking of the heap.
91
92       - 0x008 Resizing of stacks and memory manager tables.
93
94       - 0x010 Heap compaction.
95
96       - 0x020 Change of GC parameters.
97
98       - 0x040 Computation of major GC slice size.
99
100       - 0x080 Calling of finalisation functions.
101
102       - 0x100 Bytecode executable search at start-up.
103
104       - 0x200 Computation of compaction triggering condition.  Default: 0.
105        *)
106
107       mutable  max_overhead : int ;  (* Heap compaction is triggered when the
108       estimated amount of "wasted" memory is more than  max_overhead  percent
109       of  the  amount  of  live data.  If max_overhead is set to 0, heap com‐
110       paction is triggered at the end of each major GC cycle (this setting is
111       intended for testing purposes only).  If max_overhead >= 1000000 , com‐
112       paction is never triggered.  Default: 500. *)
113
114       mutable stack_limit : int ;  (* The  maximum  size  of  the  stack  (in
115       words).   This is only relevant to the byte-code runtime, as the native
116       code runtime uses the operating system's stack.  Default: 256k. *)
117
118       mutable allocation_policy : int ;  (* The policy used for allocating in
119       the  heap.   Possible  values  are  0 and 1.  0 is the next-fit policy,
120       which is quite  fast  but  can  result  in  fragmentation.   1  is  the
121       first-fit  policy,  which can be slower in some cases but can be better
122       for programs with fragmentation problems.  Default: 0. *)
123        }
124
125
126       The GC parameters are given as  a  control  record.   Note  that  these
127       parameters  can  also be initialised by setting the OCAMLRUNPARAM envi‐
128       ronment variable.  See the documentation of ocamlrun.
129
130
131
132
133       val stat : unit -> stat
134
135       Return the current values of the memory management counters in  a  stat
136       record.  This function examines every heap block to get the statistics.
137
138
139
140
141       val quick_stat : unit -> stat
142
143       Same  as  stat  except  that  live_words  ,  live_blocks , free_words ,
144       free_blocks , largest_free , and fragments are set to 0.  This function
145       is  much  faster  than  stat because it does not need to go through the
146       heap.
147
148
149
150
151       val counters : unit -> float * float * float
152
153       Return (minor_words, promoted_words, major_words) .  This  function  is
154       as fast at quick_stat .
155
156
157
158
159       val get : unit -> control
160
161       Return the current values of the GC parameters in a control record.
162
163
164
165
166       val set : control -> unit
167
168
169       set  r  changes  the  GC parameters according to the control record r .
170       The normal usage is: Gc.set { (Gc.get()) with Gc.verbose = 0x00d }
171
172
173
174
175
176       val minor : unit -> unit
177
178       Trigger a minor collection.
179
180
181
182
183       val major_slice : int -> int
184
185       Do a minor collection and a slice of major collection.  The argument is
186       the  size of the slice, 0 to use the automatically-computed slice size.
187       In all cases, the result is the computed slice size.
188
189
190
191
192       val major : unit -> unit
193
194       Do a minor collection and finish the current major collection cycle.
195
196
197
198
199       val full_major : unit -> unit
200
201       Do a minor collection, finish the current major collection  cycle,  and
202       perform a complete new cycle.  This will collect all currently unreach‐
203       able blocks.
204
205
206
207
208       val compact : unit -> unit
209
210       Perform a full major collection and compact the heap.  Note  that  heap
211       compaction is a lengthy operation.
212
213
214
215
216       val print_stat : Pervasives.out_channel -> unit
217
218       Print  the  current  values  of  the  memory  management  counters  (in
219       human-readable form) into the channel argument.
220
221
222
223
224       val allocated_bytes : unit -> float
225
226       Return the total number  of  bytes  allocated  since  the  program  was
227       started.  It is returned as a float to avoid overflow problems with int
228       on 32-bit machines.
229
230
231
232
233       val finalise : ('a -> unit) -> 'a -> unit
234
235
236       finalise f v registers f as a finalisation function for v .  v must  be
237       heap-allocated.   f  will  be  called  with v as argument at some point
238       between the first time v becomes unreachable and the  time  v  is  col‐
239       lected  by  the  GC.   Several functions can be registered for the same
240       value, or even several instances of the same function.   Each  instance
241       will  be  called  once  (or  never,  if the program terminates before v
242       becomes unreachable).
243
244       The GC will call the finalisation functions in the order  of  dealloca‐
245       tion.   When  several  values become unreachable at the same time (i.e.
246       during the same GC cycle), the finalisation functions will be called in
247       the reverse order of the corresponding calls to finalise .  If finalise
248       is called in the same order as the values  are  allocated,  that  means
249       each  value is finalised before the values it depends upon.  Of course,
250       this becomes false if additional dependencies are introduced by assign‐
251       ments.
252
253       Anything  reachable  from the closure of finalisation functions is con‐
254       sidered reachable, so the following code will not work as expected:
255
256       - let v = ... in Gc.finalise (fun x -> ...) v
257
258       Instead you should write:
259
260       - let f = fun x -> ... ;; let v = ... in Gc.finalise f v
261
262       The f function can use all features of  O'Caml,  including  assignments
263       that make the value reachable again.  It can also loop forever (in this
264       case, the other finalisation functions will be called during the execu‐
265       tion  of  f).   It  can  call finalise on v or other values to register
266       other functions or even itself.  It can raise  an  exception;  in  this
267       case  the  exception will interrupt whatever the program was doing when
268       the function was called.
269
270
271       finalise will raise Invalid_argument if v is not heap-allocated.   Some
272       examples  of  values that are not heap-allocated are integers, constant
273       constructors, booleans, the empty  array,  the  empty  list,  the  unit
274       value.   The exact list of what is heap-allocated or not is implementa‐
275       tion-dependent.  Some constant values can be heap-allocated  but  never
276       deallocated  during  the lifetime of the program, for example a list of
277       integer constants; this is also implementation-dependent.   You  should
278       also  be aware that compiler optimisations may duplicate some immutable
279       values, for example floating-point numbers when stored into arrays,  so
280       they  can be finalised and collected while another copy is still in use
281       by the program.
282
283       The results of calling String.make , String.create , Array.make  ,  and
284       Pervasives.ref  are  guaranteed  to  be heap-allocated and non-constant
285       except when the length argument is 0 .
286
287
288
289
290       val finalise_release : unit -> unit
291
292       A finalisation function may call finalise_release to tell the  GC  that
293       it  can  launch  the next finalisation function without waiting for the
294       current one to return.
295
296
297
298       type alarm
299
300
301       An alarm is a piece of data that calls a user function at  the  end  of
302       each  major  GC  cycle.  The following functions are provided to create
303       and delete alarms.
304
305
306
307
308       val create_alarm : (unit -> unit) -> alarm
309
310
311       create_alarm f will arrange for f to be called at the end of each major
312       GC  cycle, starting with the current cycle or the next one.  A value of
313       type alarm is returned that you can use to call delete_alarm .
314
315
316
317
318       val delete_alarm : alarm -> unit
319
320
321       delete_alarm a will stop the calls to the function associated  to  a  .
322       Calling delete_alarm a again has no effect.
323
324
325
326
327
328
329OCamldoc                          2017-03-22                             Gc(3)
Impressum