1Stdlib.Gc(3) OCaml library Stdlib.Gc(3)
2
6 Stdlib.Gc - no description
7
9 Module Stdlib.Gc
10
12 Module Gc
13 : (module Stdlib__Gc)
14 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 Note that "live" words refers to every word in the major heap that
47 isn't currently known to be collectable, which includes words that have
48 become unreachable by the program after the start of the previous gc
49 cycle. It is typically much simpler and more predictable to call
50 Gc.full_major (or Gc.compact ) then computing gc stats, as then "live"
51 words has the simple meaning of "reachable by the program". One caveat
52 is that a single call to Gc.full_major will not reclaim values that
53 have a finaliser from Gc.finalise (this does not apply to Gc.fi‐
54 nalise_last ). If this caveat matters, simply call Gc.full_major twice
55 instead of once.
56 *)
57 live_blocks : int ; (* Number of live blocks in the major heap.
58 See live_words for a caveat about what "live" means.
60 *)
61 free_words : int ; (* Number of words in the free list.
62 *)
63 free_blocks : int ; (* Number of blocks in the free list.
64 *)
65 largest_free : int ; (* Size (in words) of the largest block in the
66 free list.
67 *)
68 fragments : int ; (* Number of wasted words due to fragmentation.
69 These are 1-words free blocks placed between two live blocks. They are
70 not available for allocation.
71 *)
72 compactions : int ; (* Number of heap compactions since the program
73 was started.
74 *)
75 top_heap_words : int ; (* Maximum size reached by the major heap, in
76 words.
77 *)
78 stack_size : int ; (* Current size of the stack, in words.
79 Since 3.12.0
82 *)
83 forced_major_collections : int ; (* Number of forced full major col‐
84 lections completed since the program was started.
85 Since 4.12.0
88 *)
89 }
90 The memory management counters are returned in a stat record. These
93 counters give values for the whole program.
94 The total amount of memory allocated by the program since it was
96 started is (in words) minor_words + major_words - promoted_words .
97 Multiply by the word size (4 on a 32-bit machine, 8 on a 64-bit ma‐
98 chine) to get the number of bytes.
99 type control = {
102 minor_heap_size : int ; (* The size (in words) of the minor heap.
103 Changing this parameter will trigger a minor collection. The total size
104 of the minor heap used by this program is the sum of the heap sizes of
105 the active domains. Default: 256k.
106 *)
107 major_heap_increment : int ; (* How much to add to the major heap
108 when increasing it. If this number is less than or equal to 1000, it is
109 a percentage of the current heap size (i.e. setting it to 100 will dou‐
110 ble the heap size at each increase). If it is more than 1000, it is a
111 fixed number of words that will be added to the heap. Default: 15.
112 *)
113 space_overhead : int ; (* The major GC speed is computed from this
114 parameter. This is the memory that will be "wasted" because the GC
115 does not immediately collect unreachable blocks. It is expressed as a
116 percentage of the memory used for live data. The GC will work more
117 (use more CPU time and collect blocks more eagerly) if space_overhead
118 is smaller. Default: 120.
119 *)
120 verbose : int ; (* This value controls the GC messages on standard
121 error output. It is a sum of some of the following flags, to print
122 messages on the corresponding events:
123 - 0x001 Start and end of major GC cycle.
125 - 0x002 Minor collection and major GC slice.
127 - 0x004 Growing and shrinking of the heap.
129 - 0x008 Resizing of stacks and memory manager tables.
131 - 0x010 Heap compaction.
133 - 0x020 Change of GC parameters.
135 - 0x040 Computation of major GC slice size.
137 - 0x080 Calling of finalisation functions.
139 - 0x100 Bytecode executable and shared library search at start-up.
141 - 0x200 Computation of compaction-triggering condition.
143 - 0x400 Output GC statistics at program exit. Default: 0.
145 *)
147 max_overhead : int ; (* Heap compaction is triggered when the esti‐
148 mated amount of "wasted" memory is more than max_overhead percent of
149 the amount of live data. If max_overhead is set to 0, heap compaction
150 is triggered at the end of each major GC cycle (this setting is in‐
151 tended for testing purposes only). If max_overhead >= 1000000 , com‐
152 paction is never triggered. If compaction is permanently disabled, it
153 is strongly suggested to set allocation_policy to 2. Default: 500.
154 *)
155 stack_limit : int ; (* The maximum size of the fiber stacks (in
156 words). Default: 1024k.
157 *)
158 allocation_policy : int ; (* The policy used for allocating in the
159 major heap. Possible values are 0, 1 and 2.
160 -0 is the next-fit policy, which is usually fast but can result in
163 fragmentation, increasing memory consumption.
164 -1 is the first-fit policy, which avoids fragmentation but has corner
167 cases (in certain realistic workloads) where it is sensibly slower.
168 -2 is the best-fit policy, which is fast and avoids fragmentation. In
171 our experiments it is faster and uses less memory than both next-fit
172 and first-fit. (since OCaml 4.10)
173 The default is best-fit.
175 On one example that was known to be bad for next-fit and first-fit,
177 next-fit takes 28s using 855Mio of memory, first-fit takes 47s using
178 566Mio of memory, best-fit takes 27s using 545Mio of memory.
179 Note: If you change to next-fit, you may need to reduce the space_over‐
181 head setting, for example using 80 instead of the default 120 which is
182 tuned for best-fit. Otherwise, your program will need more memory.
183 Note: changing the allocation policy at run-time forces a heap com‐
185 paction, which is a lengthy operation unless the heap is small (e.g. at
186 the start of the program).
187 Default: 2.
189 Since 3.11.0
192 *)
193 window_size : int ; (* The size of the window used by the major GC
194 for smoothing out variations in its workload. This is an integer be‐
195 tween 1 and 50. Default: 1.
196 Since 4.03.0
199 *)
200 custom_major_ratio : int ; (* Target ratio of floating garbage to ma‐
201 jor heap size for out-of-heap memory held by custom values located in
202 the major heap. The GC speed is adjusted to try to use this much memory
203 for dead values that are not yet collected. Expressed as a percentage
204 of major heap size. The default value keeps the out-of-heap floating
205 garbage about the same size as the in-heap overhead. Note: this only
206 applies to values allocated with caml_alloc_custom_mem (e.g. bigar‐
207 rays). Default: 44.
208 Since 4.08.0
211 *)
212 custom_minor_ratio : int ; (* Bound on floating garbage for
213 out-of-heap memory held by custom values in the minor heap. A minor GC
214 is triggered when this much memory is held by custom values located in
215 the minor heap. Expressed as a percentage of minor heap size. Note:
216 this only applies to values allocated with caml_alloc_custom_mem (e.g.
217 bigarrays). Default: 100.
218 Since 4.08.0
221 *)
222 custom_minor_max_size : int ; (* Maximum amount of out-of-heap memory
223 for each custom value allocated in the minor heap. When a custom value
224 is allocated on the minor heap and holds more than this many bytes,
225 only this value is counted against custom_minor_ratio and the rest is
226 directly counted against custom_major_ratio . Note: this only applies
227 to values allocated with caml_alloc_custom_mem (e.g. bigarrays). De‐
228 fault: 8192 bytes.
229 Since 4.08.0
232 *)
233 }
234 The GC parameters are given as a control record. Note that these pa‐
237 rameters can also be initialised by setting the OCAMLRUNPARAM environ‐
238 ment variable. See the documentation of ocamlrun .
239 val stat : unit -> stat
243 Return the current values of the memory management counters in a stat
245 record that represent the program's total memory stats. This function
246 causes a full major collection.
247 val quick_stat : unit -> stat
251 Same as stat except that live_words , live_blocks , free_words ,
253 free_blocks , largest_free , and fragments are set to 0. Due to per-do‐
254 main buffers it may only represent the state of the program's total
255 memory usage since the last minor collection. This function is much
256 faster than stat because it does not need to trigger a full major col‐
257 lection.
258 val counters : unit -> float * float * float
262 Return (minor_words, promoted_words, major_words) for the current do‐
264 main or potentially previous domains. This function is as fast as
265 quick_stat .
266 val minor_words : unit -> float
270 Number of words allocated in the minor heap by this domain or poten‐
272 tially previous domains. This number is accurate in byte-code programs,
273 but only an approximation in programs compiled to native code.
274 In native code this function does not allocate.
276 Since 4.04
279 val get : unit -> control
283 Return the current values of the GC parameters in a control record.
285 Alert unsynchronized_access. GC parameters are a mutable global state.
288 val set : control -> unit
292 set r changes the GC parameters according to the control record r .
295 The normal usage is: Gc.set { (Gc.get()) with Gc.verbose = 0x00d }
296 Alert unsynchronized_access. GC parameters are a mutable global state.
300 val minor : unit -> unit
304 Trigger a minor collection.
306 val major_slice : int -> int
310 major_slice n Do a minor collection and a slice of major collection. n
313 is the size of the slice: the GC will do enough work to free (on aver‐
314 age) n words of memory. If n = 0, the GC will try to do enough work to
315 ensure that the next automatic slice has no work to do. This function
316 returns an unspecified integer (currently: 0).
317 val major : unit -> unit
321 Do a minor collection and finish the current major collection cycle.
323 val full_major : unit -> unit
327 Do a minor collection, finish the current major collection cycle, and
329 perform a complete new cycle. This will collect all currently unreach‐
330 able blocks.
331 val compact : unit -> unit
335 Perform a full major collection and compact the heap. Note that heap
337 compaction is a lengthy operation.
338 val print_stat : out_channel -> unit
342 Print the current values of the memory management counters (in hu‐
344 man-readable form) of the total program into the channel argument.
345 val allocated_bytes : unit -> float
349 Return the number of bytes allocated by this domain and potentially a
351 previous domain. It is returned as a float to avoid overflow problems
352 with int on 32-bit machines.
353 val get_minor_free : unit -> int
357 Return the current size of the free space inside the minor heap of this
359 domain.
360 Since 4.03.0
363 val finalise : ('a -> unit) -> 'a -> unit
367 finalise f v registers f as a finalisation function for v . v must be
370 heap-allocated. f will be called with v as argument at some point be‐
371 tween the first time v becomes unreachable (including through weak
372 pointers) and the time v is collected by the GC. Several functions can
373 be registered for the same value, or even several instances of the same
374 function. Each instance will be called once (or never, if the program
375 terminates before v becomes unreachable).
376 The GC will call the finalisation functions in the order of dealloca‐
378 tion. When several values become unreachable at the same time (i.e.
379 during the same GC cycle), the finalisation functions will be called in
380 the reverse order of the corresponding calls to finalise . If finalise
381 is called in the same order as the values are allocated, that means
382 each value is finalised before the values it depends upon. Of course,
383 this becomes false if additional dependencies are introduced by assign‐
384 ments.
385 In the presence of multiple OCaml threads it should be assumed that any
387 particular finaliser may be executed in any of the threads.
388 Anything reachable from the closure of finalisation functions is con‐
390 sidered reachable, so the following code will not work as expected:
391 - let v = ... in Gc.finalise (fun _ -> ...v...) v
393 Instead you should make sure that v is not in the closure of the final‐
395 isation function by writing:
396 - let f = fun x -> ... let v = ... in Gc.finalise f v
398 The f function can use all features of OCaml, including assignments
400 that make the value reachable again. It can also loop forever (in this
401 case, the other finalisation functions will not be called during the
402 execution of f, unless it calls finalise_release ). It can call fi‐
403 nalise on v or other values to register other functions or even itself.
404 It can raise an exception; in this case the exception will interrupt
405 whatever the program was doing when the function was called.
406 finalise will raise Invalid_argument if v is not guaranteed to be
409 heap-allocated. Some examples of values that are not heap-allocated
410 are integers, constant constructors, booleans, the empty array, the
411 empty list, the unit value. The exact list of what is heap-allocated
412 or not is implementation-dependent. Some constant values can be
413 heap-allocated but never deallocated during the lifetime of the pro‐
414 gram, for example a list of integer constants; this is also implementa‐
415 tion-dependent. Note that values of types float are sometimes allo‐
416 cated and sometimes not, so finalising them is unsafe, and finalise
417 will also raise Invalid_argument for them. Values of type 'a Lazy.t
418 (for any 'a ) are like float in this respect, except that the compiler
419 sometimes optimizes them in a way that prevents finalise from detecting
420 them. In this case, it will not raise Invalid_argument , but you should
421 still avoid calling finalise on lazy values.
422 The results of calling String.make , Bytes.make , Bytes.create , Ar‐
424 ray.make , and ref are guaranteed to be heap-allocated and non-constant
425 except when the length argument is 0 .
426 val finalise_last : (unit -> unit) -> 'a -> unit
430 same as Gc.finalise except the value is not given as argument. So you
432 can't use the given value for the computation of the finalisation func‐
433 tion. The benefit is that the function is called after the value is un‐
434 reachable for the last time instead of the first time. So contrary to
435 Gc.finalise the value will never be reachable again or used again. In
436 particular every weak pointer and ephemeron that contained this value
437 as key or data is unset before running the finalisation function. More‐
438 over the finalisation functions attached with Gc.finalise are always
439 called before the finalisation functions attached with Gc.finalise_last
440 .
441 Since 4.04
444 val finalise_release : unit -> unit
448 A finalisation function may call finalise_release to tell the GC that
450 it can launch the next finalisation function without waiting for the
451 current one to return.
452 type alarm
455 An alarm is a piece of data that calls a user function at the end of
458 each major GC cycle. The following functions are provided to create
459 and delete alarms.
460 val create_alarm : (unit -> unit) -> alarm
464 create_alarm f will arrange for f to be called at the end of each major
467 GC cycle, starting with the current cycle or the next one. A value of
468 type alarm is returned that you can use to call delete_alarm .
469 val delete_alarm : alarm -> unit
473 delete_alarm a will stop the calls to the function associated to a .
476 Calling delete_alarm a again has no effect.
477 val eventlog_pause : unit -> unit
481 Deprecated. Use Runtime_events.pause instead.
483 val eventlog_resume : unit -> unit
487 Deprecated. Use Runtime_events.resume instead.
489 module Memprof : sig end
492 Memprof is a sampling engine for allocated memory words. Every allo‐
496 cated word has a probability of being sampled equal to a configurable
497 sampling rate. Once a block is sampled, it becomes tracked. A tracked
498 block triggers a user-defined callback as soon as it is allocated, pro‐
499 moted or deallocated.
500 Since blocks are composed of several words, a block can potentially be
502 sampled several times. If a block is sampled several times, then each
503 of the callback is called once for each event of this block: the multi‐
504 plicity is given in the n_samples field of the allocation structure.
505 This engine makes it possible to implement a low-overhead memory pro‐
507 filer as an OCaml library.
508 Note: this API is EXPERIMENTAL. It may change without prior notice.
510OCamldoc 2023-07-20 Stdlib.Gc(3)