.TH "Gc" 3o source: 2019-01-25 OCamldoc "OCaml library" .SH NAME Gc \- Memory management control and statistics; finalised values. .SH Module Module Gc .SH Documentation .sp Module .BI "Gc" : .B sig end .sp Memory management control and statistics; finalised values\&. .sp .sp .sp .I type stat = { minor_words : .B float ; (* Number of words allocated in the minor heap since the program was started\&. This number is accurate in byte\-code programs, but only an approximation in programs compiled to native code\&. *) promoted_words : .B float ; (* Number of words allocated in the minor heap that survived a minor collection and were moved to the major heap since the program was started\&. *) major_words : .B float ; (* Number of words allocated in the major heap, including the promoted words, since the program was started\&. *) minor_collections : .B int ; (* Number of minor collections since the program was started\&. *) major_collections : .B int ; (* Number of major collection cycles completed since the program was started\&. *) heap_words : .B int ; (* Total size of the major heap, in words\&. *) heap_chunks : .B int ; (* Number of contiguous pieces of memory that make up the major heap\&. *) live_words : .B int ; (* Number of words of live data in the major heap, including the header words\&. *) live_blocks : .B int ; (* Number of live blocks in the major heap\&. *) free_words : .B int ; (* Number of words in the free list\&. *) free_blocks : .B int ; (* Number of blocks in the free list\&. *) largest_free : .B int ; (* Size (in words) of the largest block in the free list\&. *) fragments : .B int ; (* Number of wasted words due to fragmentation\&. These are 1\-words free blocks placed between two live blocks\&. They are not available for allocation\&. *) compactions : .B int ; (* Number of heap compactions since the program was started\&. *) top_heap_words : .B int ; (* Maximum size reached by the major heap, in words\&. *) stack_size : .B int ; (* Current size of the stack, in words\&. .sp .B "Since" 3.12.0 *) } .sp The memory management counters are returned in a .B stat record\&. .sp The total amount of memory allocated by the program since it was started is (in words) .B minor_words + major_words \- promoted_words \&. Multiply by the word size (4 on a 32\-bit machine, 8 on a 64\-bit machine) to get the number of bytes\&. .sp .I type control = { .B mutable minor_heap_size : .B int ; (* The size (in words) of the minor heap\&. Changing this parameter will trigger a minor collection\&. Default: 256k\&. *) .B mutable major_heap_increment : .B int ; (* How much to add to the major heap when increasing it\&. If this number is less than or equal to 1000, it is a percentage of the current heap size (i\&.e\&. setting it to 100 will double the heap size at each increase)\&. If it is more than 1000, it is a fixed number of words that will be added to the heap\&. Default: 15\&. *) .B mutable space_overhead : .B int ; (* The major GC speed is computed from this parameter\&. This is the memory that will be "wasted" because the GC does not immediatly collect unreachable blocks\&. It is expressed as a percentage of the memory used for live data\&. The GC will work more (use more CPU time and collect blocks more eagerly) if .B space_overhead is smaller\&. Default: 80\&. *) .B mutable verbose : .B int ; (* This value controls the GC messages on standard error output\&. It is a sum of some of the following flags, to print messages on the corresponding events: .sp \- .B 0x001 Start of major GC cycle\&. .sp \- .B 0x002 Minor collection and major GC slice\&. .sp \- .B 0x004 Growing and shrinking of the heap\&. .sp \- .B 0x008 Resizing of stacks and memory manager tables\&. .sp \- .B 0x010 Heap compaction\&. .sp \- .B 0x020 Change of GC parameters\&. .sp \- .B 0x040 Computation of major GC slice size\&. .sp \- .B 0x080 Calling of finalisation functions\&. .sp \- .B 0x100 Bytecode executable and shared library search at start\-up\&. .sp \- .B 0x200 Computation of compaction\-triggering condition\&. .sp \- .B 0x400 Output GC statistics at program exit\&. Default: 0\&. *) .B mutable max_overhead : .B int ; (* Heap compaction is triggered when the estimated amount of "wasted" memory is more than .B max_overhead percent of the amount of live data\&. If .B max_overhead is set to 0, heap compaction is triggered at the end of each major GC cycle (this setting is intended for testing purposes only)\&. If .B max_overhead >= 1000000 , compaction is never triggered\&. If compaction is permanently disabled, it is strongly suggested to set .B allocation_policy to 1\&. Default: 500\&. *) .B mutable stack_limit : .B int ; (* The maximum size of the stack (in words)\&. This is only relevant to the byte\-code runtime, as the native code runtime uses the operating system\&'s stack\&. Default: 1024k\&. *) .B mutable allocation_policy : .B int ; (* The policy used for allocating in the heap\&. Possible values are 0 and 1\&. 0 is the next\-fit policy, which is quite fast but can result in fragmentation\&. 1 is the first\-fit policy, which can be slower in some cases but can be better for programs with fragmentation problems\&. Default: 0\&. .sp .B "Since" 3.11.0 *) window_size : .B int ; (* The size of the window used by the major GC for smoothing out variations in its workload\&. This is an integer between 1 and 50\&. Default: 1\&. .sp .B "Since" 4.03.0 *) } .sp The GC parameters are given as a .B control record\&. Note that these parameters can also be initialised by setting the OCAMLRUNPARAM environment variable\&. See the documentation of .B ocamlrun \&. .sp .I val stat : .B unit -> stat .sp Return the current values of the memory management counters in a .B stat record\&. This function examines every heap block to get the statistics\&. .sp .I val quick_stat : .B unit -> stat .sp Same as .B stat except that .B live_words , .B live_blocks , .B free_words , .B free_blocks , .B largest_free , and .B fragments are set to 0\&. This function is much faster than .B stat because it does not need to go through the heap\&. .sp .I val counters : .B unit -> float * float * float .sp Return .B (minor_words, promoted_words, major_words) \&. This function is as fast as .B quick_stat \&. .sp .I val minor_words : .B unit -> float .sp Number of words allocated in the minor heap since the program was started\&. This number is accurate in byte\-code programs, but only an approximation in programs compiled to native code\&. .sp In native code this function does not allocate\&. .sp .B "Since" 4.04 .sp .I val get : .B unit -> control .sp Return the current values of the GC parameters in a .B control record\&. .sp .I val set : .B control -> unit .sp .B set r changes the GC parameters according to the .B control record .B r \&. The normal usage is: .B Gc\&.set { (Gc\&.get()) with Gc\&.verbose = 0x00d } .sp .I val minor : .B unit -> unit .sp Trigger a minor collection\&. .sp .I val major_slice : .B int -> int .sp .B major_slice n Do a minor collection and a slice of major collection\&. .B n is the size of the slice: the GC will do enough work to free (on average) .B n words of memory\&. If .B n = 0, the GC will try to do enough work to ensure that the next automatic slice has no work to do\&. This function returns an unspecified integer (currently: 0)\&. .sp .I val major : .B unit -> unit .sp Do a minor collection and finish the current major collection cycle\&. .sp .I val full_major : .B unit -> unit .sp Do a minor collection, finish the current major collection cycle, and perform a complete new cycle\&. This will collect all currently unreachable blocks\&. .sp .I val compact : .B unit -> unit .sp Perform a full major collection and compact the heap\&. Note that heap compaction is a lengthy operation\&. .sp .I val print_stat : .B Pervasives.out_channel -> unit .sp Print the current values of the memory management counters (in human\-readable form) into the channel argument\&. .sp .I val allocated_bytes : .B unit -> float .sp Return the total number of bytes allocated since the program was started\&. It is returned as a .B float to avoid overflow problems with .B int on 32\-bit machines\&. .sp .I val get_minor_free : .B unit -> int .sp Return the current size of the free space inside the minor heap\&. .sp .B "Since" 4.03.0 .sp .I val get_bucket : .B int -> int .sp .B get_bucket n returns the current size of the .B n \-th future bucket of the GC smoothing system\&. The unit is one millionth of a full GC\&. Raise .B Invalid_argument if .B n is negative, return 0 if n is larger than the smoothing window\&. .sp .B "Since" 4.03.0 .sp .I val get_credit : .B unit -> int .sp .B get_credit () returns the current size of the "work done in advance" counter of the GC smoothing system\&. The unit is one millionth of a full GC\&. .sp .B "Since" 4.03.0 .sp .I val huge_fallback_count : .B unit -> int .sp Return the number of times we tried to map huge pages and had to fall back to small pages\&. This is always 0 if .B OCAMLRUNPARAM contains .B H=1 \&. .sp .B "Since" 4.03.0 .sp .I val finalise : .B ('a -> unit) -> 'a -> unit .sp .B finalise f v registers .B f as a finalisation function for .B v \&. .B v must be heap\-allocated\&. .B f will be called with .B v as argument at some point between the first time .B v becomes unreachable (including through weak pointers) and the time .B v is collected by the GC\&. Several functions can be registered for the same value, or even several instances of the same function\&. Each instance will be called once (or never, if the program terminates before .B v becomes unreachable)\&. .sp The GC will call the finalisation functions in the order of deallocation\&. When several values become unreachable at the same time (i\&.e\&. during the same GC cycle), the finalisation functions will be called in the reverse order of the corresponding calls to .B finalise \&. If .B finalise is called in the same order as the values are allocated, that means each value is finalised before the values it depends upon\&. Of course, this becomes false if additional dependencies are introduced by assignments\&. .sp In the presence of multiple OCaml threads it should be assumed that any particular finaliser may be executed in any of the threads\&. .sp Anything reachable from the closure of finalisation functions is considered reachable, so the following code will not work as expected: .sp \- .B let v = \&.\&.\&. in Gc\&.finalise (fun _ \-> \&.\&.\&.v\&.\&.\&.) v Instead you should make sure that .B v is not in the closure of the finalisation function by writing: .sp \- .B let f = fun x \-> \&.\&.\&. let v = \&.\&.\&. in Gc\&.finalise f v The .B f function can use all features of OCaml, including assignments that make the value reachable again\&. It can also loop forever (in this case, the other finalisation functions will not be called during the execution of f, unless it calls .B finalise_release )\&. It can call .B finalise on .B v or other values to register other functions or even itself\&. It can raise an exception; in this case the exception will interrupt whatever the program was doing when the function was called\&. .sp .B finalise will raise .B Invalid_argument if .B v is not guaranteed to be heap\-allocated\&. Some examples of values that are not heap\-allocated are integers, constant constructors, booleans, the empty array, the empty list, the unit value\&. The exact list of what is heap\-allocated or not is implementation\-dependent\&. Some constant values can be heap\-allocated but never deallocated during the lifetime of the program, for example a list of integer constants; this is also implementation\-dependent\&. Note that values of types .B float are sometimes allocated and sometimes not, so finalising them is unsafe, and .B finalise will also raise .B Invalid_argument for them\&. Values of type .B \&'a Lazy\&.t (for any .B \&'a ) are like .B float in this respect, except that the compiler sometimes optimizes them in a way that prevents .B finalise from detecting them\&. In this case, it will not raise .B Invalid_argument , but you should still avoid calling .B finalise on lazy values\&. .sp The results of calling .B String\&.make , .B Bytes\&.make , .B Bytes\&.create , .B Array\&.make , and .B Pervasives\&.ref are guaranteed to be heap\-allocated and non\-constant except when the length argument is .B 0 \&. .sp .I val finalise_last : .B (unit -> unit) -> 'a -> unit .sp same as .B Gc\&.finalise except the value is not given as argument\&. So you can\&'t use the given value for the computation of the finalisation function\&. The benefit is that the function is called after the value is unreachable for the last time instead of the first time\&. So contrary to .B Gc\&.finalise the value will never be reachable again or used again\&. In particular every weak pointer and ephemeron that contained this value as key or data is unset before running the finalisation function\&. Moreover the finalisation function attached with `GC\&.finalise` are always called before the finalisation function attached with `GC\&.finalise_last`\&. .sp .B "Since" 4.04 .sp .I val finalise_release : .B unit -> unit .sp A finalisation function may call .B finalise_release to tell the GC that it can launch the next finalisation function without waiting for the current one to return\&. .sp .I type alarm .sp An alarm is a piece of data that calls a user function at the end of each major GC cycle\&. The following functions are provided to create and delete alarms\&. .sp .I val create_alarm : .B (unit -> unit) -> alarm .sp .B create_alarm f will arrange for .B f to be called at the end of each major GC cycle, starting with the current cycle or the next one\&. A value of type .B alarm is returned that you can use to call .B delete_alarm \&. .sp .I val delete_alarm : .B alarm -> unit .sp .B delete_alarm a will stop the calls to the function associated to .B a \&. Calling .B delete_alarm a again has no effect\&. .sp