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

NAME

6       Stdlib.Gc - no description
7

Module

9       Module   Stdlib.Gc
10

Documentation

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