commit 905cbb6a3ebf1edc11745737feeedd36708149a7 Author: KC Sivaramakrishnan Date: Wed Mar 23 10:11:46 2016 +0000 Spacing edits diff --git a/src/batGc.mli b/src/batGc.mli index ecffb79..494b9b1 100644 --- a/src/batGc.mli +++ b/src/batGc.mli @@ -34,18 +34,18 @@ type stat = Gc.stat = { minor_words : 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. *) + the program was started. This number is accurate in + byte-code programs, but only an approximation in programs + compiled to native code. *) promoted_words : 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. *) + survived a minor collection and were moved to the major heap + since the program was started. *) major_words : float; (** Number of words allocated in the major heap, including - the promoted words, since the program was started. *) + the promoted words, since the program was started. *) minor_collections : int; (** Number of minor collections since the program was started. *) @@ -62,7 +62,7 @@ type stat = Gc.stat = live_words : int; (** Number of words of live data in the major heap, including the header - words. *) + words. *) live_blocks : int; (** Number of live blocks in the major heap. *) @@ -78,8 +78,8 @@ type stat = Gc.stat = fragments : 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. *) + 1-words free blocks placed between two live blocks. They + are not available for allocation. *) compactions : int; (** Number of heap compactions since the program was started. *) @@ -92,16 +92,16 @@ type stat = Gc.stat = } (** The memory management counters are returned in a [stat] record. - The total amount of memory allocated by the program since it was started - is (in words) [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. + The total amount of memory allocated by the program since it was started + is (in words) [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. *) type control = Gc.control = { mutable minor_heap_size : int; (** The size (in words) of the minor heap. Changing - this parameter will trigger a minor collection. Default: 256k. *) + this parameter will trigger a minor collection. Default: 256k. *) mutable major_heap_increment : int; (** How much to add to the major heap when increasing it. If this @@ -112,45 +112,45 @@ type control = Gc.control = mutable space_overhead : 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 [space_overhead] is smaller. - Default: 80. *) + 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 [space_overhead] is smaller. + Default: 80. *) mutable verbose : 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: - - [0x001] Start of major GC cycle. - - [0x002] Minor collection and major GC slice. - - [0x004] Growing and shrinking of the heap. - - [0x008] Resizing of stacks and memory manager tables. - - [0x010] Heap compaction. - - [0x020] Change of GC parameters. - - [0x040] Computation of major GC slice size. - - [0x080] Calling of finalisation functions. - - [0x100] Bytecode executable and shared library search at start-up. - - [0x200] Computation of compaction-triggering condition. - - [0x400] Output GC statistics at program exit. - Default: 0. *) + It is a sum of some of the following flags, to print messages + on the corresponding events: + - [0x001] Start of major GC cycle. + - [0x002] Minor collection and major GC slice. + - [0x004] Growing and shrinking of the heap. + - [0x008] Resizing of stacks and memory manager tables. + - [0x010] Heap compaction. + - [0x020] Change of GC parameters. + - [0x040] Computation of major GC slice size. + - [0x080] Calling of finalisation functions. + - [0x100] Bytecode executable and shared library search at start-up. + - [0x200] Computation of compaction-triggering condition. + - [0x400] Output GC statistics at program exit. + Default: 0. *) mutable max_overhead : int; (** Heap compaction is triggered when the estimated amount - of "wasted" memory is more than [max_overhead] percent of the - amount of live data. If [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 [max_overhead >= 1000000], compaction is never triggered. - If compaction is permanently disabled, it is strongly suggested - to set [allocation_policy] to 1. - Default: 500. *) + of "wasted" memory is more than [max_overhead] percent of the + amount of live data. If [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 [max_overhead >= 1000000], compaction is never triggered. + If compaction is permanently disabled, it is strongly suggested + to set [allocation_policy] to 1. + Default: 500. *) mutable stack_limit : 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. *) + relevant to the byte-code runtime, as the native code runtime + uses the operating system's stack. Default: 1024k. *) mutable allocation_policy : int; (** The policy used for allocating in the heap. Possible @@ -173,8 +173,8 @@ type control = Gc.control = external stat : unit -> stat = "caml_gc_stat" (** Return the current values of the memory management counters in a - [stat] record. This function examines every heap block to get the - statistics. *) + [stat] record. This function examines every heap block to get the + statistics. *) external quick_stat : unit -> stat = "caml_gc_quick_stat" (** Same as [stat] except that [live_words], [live_blocks], [free_words], @@ -191,7 +191,7 @@ external get : unit -> control = "caml_gc_get" external set : control -> unit = "caml_gc_set" (** [set r] changes the GC parameters according to the [control] record [r]. - The normal usage is: [Gc.set { (Gc.get()) with Gc.verbose = 0x00d }] *) + The normal usage is: [Gc.set { (Gc.get()) with Gc.verbose = 0x00d }] *) external minor : unit -> unit = "caml_gc_minor" (** Trigger a minor collection. *) @@ -210,21 +210,21 @@ external major : unit -> unit = "caml_gc_major" external full_major : unit -> unit = "caml_gc_full_major" (** Do a minor collection, finish the current major collection cycle, - and perform a complete new cycle. This will collect all currently - unreachable blocks. *) + and perform a complete new cycle. This will collect all currently + unreachable blocks. *) external compact : unit -> unit = "caml_gc_compaction" (** Perform a full major collection and compact the heap. Note that heap - compaction is a lengthy operation. *) + compaction is a lengthy operation. *) val print_stat : _ BatInnerIO.output -> unit (** Print the current values of the memory management counters (in - human-readable form) into the channel argument. *) + human-readable form) into the channel argument. *) val allocated_bytes : unit -> float (** Return the total number of bytes allocated since the program was - started. It is returned as a [float] to avoid overflow problems - with [int] on 32-bit machines. *) + started. It is returned as a [float] to avoid overflow problems + with [int] on 32-bit machines. *) external get_minor_free : unit -> int = "caml_get_minor_free" [@@noalloc] (** Return the current size of the free space inside the minor heap. *) @@ -247,63 +247,63 @@ external huge_fallback_count : unit -> int = "caml_gc_huge_fallback_count" val finalise : ('a -> unit) -> 'a -> unit (** [finalise f v] registers [f] as a finalisation function for [v]. - [v] must be heap-allocated. [f] will be called with [v] as - argument at some point between the first time [v] becomes unreachable - (including through weak pointers) and the time [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 [v] becomes unreachable). - - 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 [finalise]. If [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. - - In the presence of multiple OCaml threads it should be assumed that - any particular finaliser may be executed in any of the threads. - - Anything reachable from the closure of finalisation functions - is considered reachable, so the following code will not work - as expected: - - [ let v = ... in Gc.finalise (fun _ -> ...v...) v ] - - Instead you should make sure that [v] is not in the closure of - the finalisation function by writing: - - [ let f = fun x -> ... ;; let v = ... in Gc.finalise f v ] - - - The [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 [finalise_release]). - It can call [finalise] on [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. - - - [finalise] will raise [Invalid_argument] if [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 [float] and ['a lazy] (for any ['a]) are - sometimes allocated and sometimes not, so finalising them is unsafe, - and [finalise] will also raise [Invalid_argument] for them. - - - The results of calling {!String.make}, {!Bytes.make}, {!Bytes.create}, - {!Array.make}, and {!Pervasives.ref} are guaranteed to be - heap-allocated and non-constant except when the length argument is [0]. + [v] must be heap-allocated. [f] will be called with [v] as + argument at some point between the first time [v] becomes unreachable + (including through weak pointers) and the time [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 [v] becomes unreachable). + + 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 [finalise]. If [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. + + In the presence of multiple OCaml threads it should be assumed that + any particular finaliser may be executed in any of the threads. + + Anything reachable from the closure of finalisation functions + is considered reachable, so the following code will not work + as expected: + - [ let v = ... in Gc.finalise (fun _ -> ...v...) v ] + + Instead you should make sure that [v] is not in the closure of + the finalisation function by writing: + - [ let f = fun x -> ... ;; let v = ... in Gc.finalise f v ] + + + The [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 [finalise_release]). + It can call [finalise] on [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. + + + [finalise] will raise [Invalid_argument] if [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 [float] and ['a lazy] (for any ['a]) are + sometimes allocated and sometimes not, so finalising them is unsafe, + and [finalise] will also raise [Invalid_argument] for them. + + + The results of calling {!String.make}, {!Bytes.make}, {!Bytes.create}, + {!Array.make}, and {!Pervasives.ref} are guaranteed to be + heap-allocated and non-constant except when the length argument is [0]. *) val finalise_release : unit -> unit @@ -313,15 +313,15 @@ val finalise_release : unit -> unit type alarm = Gc.alarm (** 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. *) + each major GC cycle. The following functions are provided to create + and delete alarms. *) val create_alarm : (unit -> unit) -> alarm (** [create_alarm f] will arrange for [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 [alarm] is returned that you can - use to call [delete_alarm]. *) + major GC cycle, starting with the current cycle or the next one. + A value of type [alarm] is returned that you can + use to call [delete_alarm]. *) val delete_alarm : alarm -> unit (** [delete_alarm a] will stop the calls to the function associated - to [a]. Calling [delete_alarm a] again has no effect. *) + to [a]. Calling [delete_alarm a] again has no effect. *)