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       type stat = {
23        minor_words  : float ;  (* Number of words allocated in the minor heap
24       since the program was started.
25        *)
26        promoted_words : float ;  (* Number of words allocated  in  the  minor
27       heap  that survived a minor collection and were moved to the major heap
28       since the program was started.
29        *)
30        major_words : float ;  (* Number of words allocated in the major heap,
31       including the promoted words, since the program was started.
32        *)
33        minor_collections  :  int  ;  (* Number of minor collections since the
34       program was started.
35        *)
36        major_collections : int ;  (* Number of major collection  cycles  com‐
37       pleted since the program was started.
38        *)
39        heap_words : int ;  (* Total size of the major heap, in words.
40        *)
41        heap_chunks  :  int  ;   (* Number of contiguous pieces of memory that
42       make up the major heap.
43        *)
44        live_words : int ;  (* Number of words of live data in the major heap,
45       including the header words.
46        *)
47        live_blocks : int ;  (* Number of live blocks in the major heap.
48        *)
49        free_words : int ;  (* Number of words in the free list.
50        *)
51        free_blocks : int ;  (* Number of blocks in the free list.
52        *)
53        largest_free  :  int ;  (* Size (in words) of the largest block in the
54       free list.
55        *)
56        fragments : int ;  (* Number of wasted  words  due  to  fragmentation.
57       These are 1-words free blocks placed between two live blocks.  They are
58       not available for allocation.
59        *)
60        compactions : int ;  (* Number of heap compactions since  the  program
61       was started.
62        *)
63        top_heap_words  : int ;  (* Maximum size reached by the major heap, in
64       words.
65        *)
66        stack_size : int ;  (* Current size of the stack, in words.
67
68
69       Since 3.12.0
70        *)
71        }
72
73
74       The memory management counters are returned in a stat record.
75
76       The total amount of memory  allocated  by  the  program  since  it  was
77       started  is  (in  words)  minor_words  + major_words - promoted_words .
78       Multiply by the word size (4  on  a  32-bit  machine,  8  on  a  64-bit
79       machine) to get the number of bytes.
80
81
82       type control = {
83
84       mutable  minor_heap_size  :  int ;  (* The size (in words) of the minor
85       heap.   Changing  this  parameter  will  trigger  a  minor  collection.
86       Default: 256k.
87        *)
88
89       mutable  major_heap_increment  : int ;  (* How much to add to the major
90       heap when increasing it. If this number is less than or equal to  1000,
91       it  is  a  percentage  of the current heap size (i.e. setting it to 100
92       will double the heap size at each increase). If it is more  than  1000,
93       it  is a fixed number of words that will be added to the heap. Default:
94       15.
95        *)
96
97       mutable space_overhead : int ;  (* The major GC speed is computed  from
98       this  parameter.   This is the memory that will be "wasted" because the
99       GC does not immediately collect unreachable blocks.  It is expressed as
100       a  percentage  of the memory used for live data.  The GC will work more
101       (use more CPU time and collect blocks more eagerly)  if  space_overhead
102       is smaller.  Default: 80.
103        *)
104
105       mutable  verbose  :  int  ;   (* This value controls the GC messages on
106       standard error output.  It is a sum of some of the following flags,  to
107       print messages on the corresponding events:
108
109       - 0x001 Start of major GC cycle.
110
111       - 0x002 Minor collection and major GC slice.
112
113       - 0x004 Growing and shrinking of the heap.
114
115       - 0x008 Resizing of stacks and memory manager tables.
116
117       - 0x010 Heap compaction.
118
119       - 0x020 Change of GC parameters.
120
121       - 0x040 Computation of major GC slice size.
122
123       - 0x080 Calling of finalisation functions.
124
125       - 0x100 Bytecode executable and shared library search at start-up.
126
127       - 0x200 Computation of compaction-triggering condition.
128
129       - 0x400 Output GC statistics at program exit.  Default: 0.
130
131        *)
132
133       mutable  max_overhead : int ;  (* Heap compaction is triggered when the
134       estimated amount of "wasted" memory is more than  max_overhead  percent
135       of  the  amount  of  live data.  If max_overhead is set to 0, heap com‐
136       paction is triggered at the end of each major GC cycle (this setting is
137       intended for testing purposes only).  If max_overhead >= 1000000 , com‐
138       paction is never triggered.  If compaction is permanently disabled,  it
139       is strongly suggested to set allocation_policy to 2.  Default: 500.
140        *)
141
142       mutable  stack_limit  :  int  ;   (*  The maximum size of the stack (in
143       words).  This is only relevant to the byte-code runtime, as the  native
144       code runtime uses the operating system's stack.  Default: 1024k.
145        *)
146
147       mutable allocation_policy : int ;  (* The policy used for allocating in
148       the major heap.  Possible values are 0, 1 and 2.
149
150
151       -0 is the next-fit policy, which is usually  fast  but  can  result  in
152       fragmentation, increasing memory consumption.
153
154
155       -1  is  the first-fit policy, which avoids fragmentation but has corner
156       cases (in certain realistic workloads) where it is sensibly slower.
157
158
159       -2 is the best-fit policy, which is fast and avoids  fragmentation.  In
160       our  experiments  it  is faster and uses less memory than both next-fit
161       and first-fit.  (since OCaml 4.10)
162
163       The current default is next-fit, as the best-fit policy is new and  not
164       yet  widely  tested.  We  expect  best-fit to become the default in the
165       future.
166
167       On one example that was known to be bad  for  next-fit  and  first-fit,
168       next-fit  takes  28s  using 855Mio of memory, first-fit takes 47s using
169       566Mio of memory, best-fit takes 27s using 545Mio of memory.
170
171       Note: When changing to a low-fragmentation policy, you may need to aug‐
172       ment  the  space_overhead setting, for example using 100 instead of the
173       default 80 which is tuned for next-fit. Indeed, the difference in frag‐
174       mentation  behavior  means  that different policies will have different
175       proportion of "wasted space" for a given  program.  Less  fragmentation
176       means  a smaller heap so, for the same amount of wasted space, a higher
177       proportion of wasted space. This makes the GC work harder,  unless  you
178       relax it by increasing space_overhead .
179
180       Note:  changing  the  allocation  policy at run-time forces a heap com‐
181       paction, which is a lengthy operation unless the heap is small (e.g. at
182       the start of the program).
183
184       Default: 0.
185
186
187       Since 3.11.0
188        *)
189        window_size  :  int  ;  (* The size of the window used by the major GC
190       for smoothing out variations  in  its  workload.  This  is  an  integer
191       between 1 and 50.  Default: 1.
192
193
194       Since 4.03.0
195        *)
196        custom_major_ratio  :  int  ;   (* Target ratio of floating garbage to
197       major heap size for out-of-heap memory held by custom values located in
198       the major heap. The GC speed is adjusted to try to use this much memory
199       for dead values that are not yet collected. Expressed as  a  percentage
200       of  major  heap  size. The default value keeps the out-of-heap floating
201       garbage about the same size as the in-heap overhead.  Note:  this  only
202       applies  to  values  allocated  with caml_alloc_custom_mem (e.g. bigar‐
203       rays).  Default: 44.
204
205
206       Since 4.08.0
207        *)
208        custom_minor_ratio  :  int  ;   (*  Bound  on  floating  garbage   for
209       out-of-heap  memory held by custom values in the minor heap. A minor GC
210       is triggered when this much memory is held by custom values located  in
211       the  minor  heap.  Expressed as a percentage of minor heap size.  Note:
212       this only applies to values allocated with caml_alloc_custom_mem  (e.g.
213       bigarrays).  Default: 100.
214
215
216       Since 4.08.0
217        *)
218        custom_minor_max_size : int ;  (* Maximum amount of out-of-heap memory
219       for each custom value allocated in the minor heap. When a custom  value
220       is  allocated  on  the  minor heap and holds more than this many bytes,
221       only this value is counted against custom_minor_ratio and the  rest  is
222       directly  counted against custom_major_ratio .  Note: this only applies
223       to  values  allocated  with  caml_alloc_custom_mem  (e.g.   bigarrays).
224       Default: 8192 bytes.
225
226
227       Since 4.08.0
228        *)
229        }
230
231
232       The  GC  parameters  are  given  as  a control record.  Note that these
233       parameters can also be initialised by setting the  OCAMLRUNPARAM  envi‐
234       ronment variable.  See the documentation of ocamlrun .
235
236
237
238       val stat : unit -> stat
239
240       Return  the  current values of the memory management counters in a stat
241       record.  This function examines every heap block to get the statistics.
242
243
244
245       val quick_stat : unit -> stat
246
247       Same as stat except  that  live_words  ,  live_blocks  ,  free_words  ,
248       free_blocks , largest_free , and fragments are set to 0.  This function
249       is much faster than stat because it does not need  to  go  through  the
250       heap.
251
252
253
254       val counters : unit -> float * float * float
255
256       Return  (minor_words,  promoted_words, major_words) .  This function is
257       as fast as quick_stat .
258
259
260
261       val minor_words : unit -> float
262
263       Number of words allocated in the  minor  heap  since  the  program  was
264       started.  This  number  is  accurate in byte-code programs, but only an
265       approximation in programs compiled to native code.
266
267       In native code this function does not allocate.
268
269
270       Since 4.04
271
272
273
274       val get : unit -> control
275
276       Return the current values of the GC parameters in a control record.
277
278
279
280       val set : control -> unit
281
282
283       set r changes the GC parameters according to the  control  record  r  .
284       The normal usage is: Gc.set { (Gc.get()) with Gc.verbose = 0x00d }
285
286
287
288
289       val minor : unit -> unit
290
291       Trigger a minor collection.
292
293
294
295       val major_slice : int -> int
296
297
298       major_slice n Do a minor collection and a slice of major collection.  n
299       is the size of the slice: the GC will do enough work to free (on  aver‐
300       age)  n words of memory. If n = 0, the GC will try to do enough work to
301       ensure that the next automatic slice has no work to do.  This  function
302       returns an unspecified integer (currently: 0).
303
304
305
306       val major : unit -> unit
307
308       Do a minor collection and finish the current major collection cycle.
309
310
311
312       val full_major : unit -> unit
313
314       Do  a  minor collection, finish the current major collection cycle, and
315       perform a complete new cycle.  This will collect all currently unreach‐
316       able blocks.
317
318
319
320       val compact : unit -> unit
321
322       Perform  a  full major collection and compact the heap.  Note that heap
323       compaction is a lengthy operation.
324
325
326
327       val print_stat : out_channel -> unit
328
329       Print  the  current  values  of  the  memory  management  counters  (in
330       human-readable form) into the channel argument.
331
332
333
334       val allocated_bytes : unit -> float
335
336       Return  the  total  number  of  bytes  allocated  since the program was
337       started.  It is returned as a float to avoid overflow problems with int
338       on 32-bit machines.
339
340
341
342       val get_minor_free : unit -> int
343
344       Return the current size of the free space inside the minor heap.
345
346
347       Since 4.03.0
348
349
350
351       val get_bucket : int -> int
352
353
354       get_bucket n returns the current size of the n -th future bucket of the
355       GC smoothing system. The unit is one millionth of  a  full  GC.   Raise
356       Invalid_argument  if  n  is  negative, return 0 if n is larger than the
357       smoothing window.
358
359
360       Since 4.03.0
361
362
363
364       val get_credit : unit -> int
365
366
367       get_credit () returns the current size of the "work  done  in  advance"
368       counter of the GC smoothing system. The unit is one millionth of a full
369       GC.
370
371
372       Since 4.03.0
373
374
375
376       val huge_fallback_count : unit -> int
377
378       Return the number of times we tried to map huge pages and had  to  fall
379       back to small pages. This is always 0 if OCAMLRUNPARAM contains H=1 .
380
381
382       Since 4.03.0
383
384
385
386       val finalise : ('a -> unit) -> 'a -> unit
387
388
389       finalise  f v registers f as a finalisation function for v .  v must be
390       heap-allocated.  f will be called with v  as  argument  at  some  point
391       between  the  first  time v becomes unreachable (including through weak
392       pointers) and the time v is collected by the GC. Several functions  can
393       be registered for the same value, or even several instances of the same
394       function.  Each instance will be called once (or never, if the  program
395       terminates before v becomes unreachable).
396
397       The  GC  will call the finalisation functions in the order of dealloca‐
398       tion.  When several values become unreachable at the  same  time  (i.e.
399       during the same GC cycle), the finalisation functions will be called in
400       the reverse order of the corresponding calls to finalise .  If finalise
401       is  called  in  the  same order as the values are allocated, that means
402       each value is finalised before the values it depends upon.  Of  course,
403       this becomes false if additional dependencies are introduced by assign‐
404       ments.
405
406       In the presence of multiple OCaml threads it should be assumed that any
407       particular finaliser may be executed in any of the threads.
408
409       Anything  reachable  from the closure of finalisation functions is con‐
410       sidered reachable, so the following code will not work as expected:
411
412       - let v = ... in Gc.finalise (fun _ -> ...v...) v
413
414       Instead you should make sure that v is not in the closure of the final‐
415       isation function by writing:
416
417       - let f = fun x -> ...  let v = ... in Gc.finalise f v
418
419       The  f  function  can  use all features of OCaml, including assignments
420       that make the value reachable again.  It can also loop forever (in this
421       case,  the  other  finalisation functions will not be called during the
422       execution of f, unless  it  calls  finalise_release  ).   It  can  call
423       finalise  on  v  or  other  values  to register other functions or even
424       itself.  It can raise an exception; in this  case  the  exception  will
425       interrupt whatever the program was doing when the function was called.
426
427
428       finalise  will  raise  Invalid_argument  if  v  is not guaranteed to be
429       heap-allocated.  Some examples of values that  are  not  heap-allocated
430       are  integers,  constant  constructors,  booleans, the empty array, the
431       empty list, the unit value.  The exact list of what  is  heap-allocated
432       or  not  is  implementation-dependent.   Some  constant  values  can be
433       heap-allocated but never deallocated during the lifetime  of  the  pro‐
434       gram, for example a list of integer constants; this is also implementa‐
435       tion-dependent.  Note that values of types float  are  sometimes  allo‐
436       cated  and  sometimes  not,  so finalising them is unsafe, and finalise
437       will also raise Invalid_argument for them. Values  of  type  'a  Lazy.t
438       (for  any 'a ) are like float in this respect, except that the compiler
439       sometimes optimizes them in a way that prevents finalise from detecting
440       them. In this case, it will not raise Invalid_argument , but you should
441       still avoid calling finalise on lazy values.
442
443       The results of  calling  String.make  ,  Bytes.make  ,  Bytes.create  ,
444       Array.make  ,  and ref are guaranteed to be heap-allocated and non-con‐
445       stant except when the length argument is 0 .
446
447
448
449       val finalise_last : (unit -> unit) -> 'a -> unit
450
451       same as Gc.finalise except the value is not given as argument.  So  you
452       can't use the given value for the computation of the finalisation func‐
453       tion. The benefit is that the function is called  after  the  value  is
454       unreachable for the last time instead of the first time. So contrary to
455       Gc.finalise the value will never be reachable again or used  again.  In
456       particular  every  weak pointer and ephemeron that contained this value
457       as key or data is unset before running the finalisation function. More‐
458       over  the  finalisation  functions attached with Gc.finalise are always
459       called before the finalisation functions attached with Gc.finalise_last
460       .
461
462
463       Since 4.04
464
465
466
467       val finalise_release : unit -> unit
468
469       A  finalisation  function may call finalise_release to tell the GC that
470       it can launch the next finalisation function without  waiting  for  the
471       current one to return.
472
473
474       type alarm
475
476
477       An  alarm  is  a piece of data that calls a user function at the end of
478       each major GC cycle.  The following functions are  provided  to  create
479       and delete alarms.
480
481
482
483       val create_alarm : (unit -> unit) -> alarm
484
485
486       create_alarm f will arrange for f to be called at the end of each major
487       GC cycle, starting with the current cycle or the next one.  A value  of
488       type alarm is returned that you can use to call delete_alarm .
489
490
491
492       val delete_alarm : alarm -> unit
493
494
495       delete_alarm  a  will  stop the calls to the function associated to a .
496       Calling delete_alarm a again has no effect.
497
498
499
500
501
502OCamldoc                          2020-02-27                             Gc(3)
Impressum