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.
356
357
358       Since 4.03.0
359
360
361       Raises Invalid_argument if n is negative, return 0 if n is larger  than
362       the smoothing window.
363
364
365
366       val get_credit : unit -> int
367
368
369       get_credit  ()  returns  the current size of the "work done in advance"
370       counter of the GC smoothing system. The unit is one millionth of a full
371       GC.
372
373
374       Since 4.03.0
375
376
377
378       val huge_fallback_count : unit -> int
379
380       Return  the  number of times we tried to map huge pages and had to fall
381       back to small pages. This is always 0 if OCAMLRUNPARAM contains H=1 .
382
383
384       Since 4.03.0
385
386
387
388       val finalise : ('a -> unit) -> 'a -> unit
389
390
391       finalise f v registers f as a finalisation function for v .  v must  be
392       heap-allocated.   f  will  be  called  with v as argument at some point
393       between the first time v becomes unreachable  (including  through  weak
394       pointers)  and the time v is collected by the GC. Several functions can
395       be registered for the same value, or even several instances of the same
396       function.   Each instance will be called once (or never, if the program
397       terminates before v becomes unreachable).
398
399       The GC will call the finalisation functions in the order  of  dealloca‐
400       tion.   When  several  values become unreachable at the same time (i.e.
401       during the same GC cycle), the finalisation functions will be called in
402       the reverse order of the corresponding calls to finalise .  If finalise
403       is called in the same order as the values  are  allocated,  that  means
404       each  value is finalised before the values it depends upon.  Of course,
405       this becomes false if additional dependencies are introduced by assign‐
406       ments.
407
408       In the presence of multiple OCaml threads it should be assumed that any
409       particular finaliser may be executed in any of the threads.
410
411       Anything reachable from the closure of finalisation functions  is  con‐
412       sidered reachable, so the following code will not work as expected:
413
414       - let v = ... in Gc.finalise (fun _ -> ...v...) v
415
416       Instead you should make sure that v is not in the closure of the final‐
417       isation function by writing:
418
419       - let f = fun x -> ...  let v = ... in Gc.finalise f v
420
421       The f function can use all features  of  OCaml,  including  assignments
422       that make the value reachable again.  It can also loop forever (in this
423       case, the other finalisation functions will not be  called  during  the
424       execution  of  f,  unless  it  calls  finalise_release  ).  It can call
425       finalise on v or other values  to  register  other  functions  or  even
426       itself.   It  can  raise  an exception; in this case the exception will
427       interrupt whatever the program was doing when the function was called.
428
429
430       finalise will raise Invalid_argument if  v  is  not  guaranteed  to  be
431       heap-allocated.   Some  examples  of values that are not heap-allocated
432       are integers, constant constructors, booleans,  the  empty  array,  the
433       empty  list,  the unit value.  The exact list of what is heap-allocated
434       or not  is  implementation-dependent.   Some  constant  values  can  be
435       heap-allocated  but  never  deallocated during the lifetime of the pro‐
436       gram, for example a list of integer constants; this is also implementa‐
437       tion-dependent.   Note  that  values of types float are sometimes allo‐
438       cated and sometimes not, so finalising them  is  unsafe,  and  finalise
439       will  also  raise  Invalid_argument  for them. Values of type 'a Lazy.t
440       (for any 'a ) are like float in this respect, except that the  compiler
441       sometimes optimizes them in a way that prevents finalise from detecting
442       them. In this case, it will not raise Invalid_argument , but you should
443       still avoid calling finalise on lazy values.
444
445       The  results  of  calling  String.make  ,  Bytes.make  , Bytes.create ,
446       Array.make , and ref are guaranteed to be heap-allocated  and  non-con‐
447       stant except when the length argument is 0 .
448
449
450
451       val finalise_last : (unit -> unit) -> 'a -> unit
452
453       same  as  Gc.finalise except the value is not given as argument. So you
454       can't use the given value for the computation of the finalisation func‐
455       tion.  The  benefit  is  that the function is called after the value is
456       unreachable for the last time instead of the first time. So contrary to
457       Gc.finalise  the  value will never be reachable again or used again. In
458       particular every weak pointer and ephemeron that contained  this  value
459       as key or data is unset before running the finalisation function. More‐
460       over the finalisation functions attached with  Gc.finalise  are  always
461       called before the finalisation functions attached with Gc.finalise_last
462       .
463
464
465       Since 4.04
466
467
468
469       val finalise_release : unit -> unit
470
471       A finalisation function may call finalise_release to tell the  GC  that
472       it  can  launch  the next finalisation function without waiting for the
473       current one to return.
474
475
476       type alarm
477
478
479       An alarm is a piece of data that calls a user function at  the  end  of
480       each  major  GC  cycle.  The following functions are provided to create
481       and delete alarms.
482
483
484
485       val create_alarm : (unit -> unit) -> alarm
486
487
488       create_alarm f will arrange for f to be called at the end of each major
489       GC  cycle, starting with the current cycle or the next one.  A value of
490       type alarm is returned that you can use to call delete_alarm .
491
492
493
494       val delete_alarm : alarm -> unit
495
496
497       delete_alarm a will stop the calls to the function associated  to  a  .
498       Calling delete_alarm a again has no effect.
499
500
501
502       val eventlog_pause : unit -> unit
503
504
505       eventlog_pause  ()  will pause the collection of traces in the runtime.
506       Traces are collected if the program is linked to the instrumented  run‐
507       time  and started with the environment variable OCAML_EVENTLOG_ENABLED.
508       Events are flushed to disk after pausing, and no  new  events  will  be
509       recorded until eventlog_resume is called.
510
511
512
513       val eventlog_resume : unit -> unit
514
515
516       eventlog_resume () will resume the collection of traces in the runtime.
517       Traces are collected if the program is linked to the instrumented  run‐
518       time  and started with the environment variable OCAML_EVENTLOG_ENABLED.
519       This call can be used after calling eventlog_pause , or if the  program
520       was started with OCAML_EVENTLOG_ENABLED=p. (which pauses the collection
521       of traces before the first event.)
522
523
524       module Memprof : sig end
525
526
527
528       Memprof is a sampling engine for allocated memory  words.  Every  allo‐
529       cated  word  has a probability of being sampled equal to a configurable
530       sampling rate. Once a block is sampled, it becomes tracked.  A  tracked
531       block triggers a user-defined callback as soon as it is allocated, pro‐
532       moted or deallocated.
533
534       Since blocks are composed of several words, a block can potentially  be
535       sampled  several  times. If a block is sampled several times, then each
536       of the callback is called once for each event of this block: the multi‐
537       plicity is given in the n_samples field of the allocation structure.
538
539       This  engine  makes it possible to implement a low-overhead memory pro‐
540       filer as an OCaml library.
541
542       Note: this API is EXPERIMENTAL. It may change without prior notice.
543
544
545
546
547
548OCamldoc                          2020-09-01                             Gc(3)
Impressum