Documented M, m, n, w, W, t, c and H options of OCAMLRUNPARAM, Fixes #8697

Changes

@@ -124,6 +124,11 @@ Working version
   in case of concurrent modifications.
   (Xavier Leroy, report by whitequark, review by David Allsopp)
 
+- #8697, #10666: add M, m, n options of the OCAMLRUNPARAM to manual and man page
+  for ocamlrun command line options
+  (Dong An and Anukriti Kumar, review by David Allsopp, Gabriel Scherer
+   and Damien Doligez)
+
 - #10605: manual, name few css classes to ease styling and maintainability.
   (Florian Angeletti, review by Wiktor Kuchta and Gabriel Scherer)
 

man/ocamlrun.m

@@ -74,11 +74,24 @@ flag in the OCAMLRUNPARAM environment variable (see below).
 .I dir
 for dynamically-loaded libraries, in addition to the standard search path.
 .TP
+.BI \-m \ file
+Print the magic number of the bytecode executable
+.I file
+and exit.
+.TP
+.B \-M
+Print the magic number expected for bytecode executables by this version
+of the runtime and exit.
+.TP
 .B \-p
 Print the names of the primitives known to this version of
 .BR ocamlrun (1)
 and exit.
 .TP
+.B \-t
+Increment the trace level for the debug runtime (ignored by the standard
+runtime).
+.TP
 .B \-v
 Direct the memory manager to print verbose messages on standard error.
 This is equivalent to setting
@@ -119,56 +132,56 @@ in the OCAMLRUNPARAM environment variable (see below).
 and an optional multiplier. If the letter is followed by anything
 else, the corresponding option is set to 1. Unknown letters
 are ignored.
-The options are documented below; the
-last six correspond to the fields of the
+The options are documented below; the options
+.B a, i, l, m, M, n, o, O, s, v, w
+correspond to the fields of the
 .B control
 record documented in
 .IR "The OCaml user's manual",
 chapter "Standard Library", section "Gc".
-\" FIXME missing: c, H, t, w, W see MPR#7870
+
+.RS 7
+.TP
+.BR a \ (allocation_policy)
+The policy used for allocating in the OCaml heap.  Possible values
+are 0 for the next-fit policy, 1 for the first-fit
+policy, and 2 for the best-fit policy. The default is 2.
+See the Gc module documentation for details.
 .TP
 .B b
 Trigger the printing of a stack backtrace
 when an uncaught exception aborts the program.
 This option takes no argument.
 .TP
-.B p
-Turn on debugging support for
-.BR ocamlyacc -generated
-parsers.  When this option is on,
-the pushdown automaton that executes the parsers prints a
-trace of its actions.  This option takes no argument.
-.TP
-.BR R
-Turn on randomization of all hash tables by default (see the
-.B Hashtbl
-module of the standard library). This option takes no
-argument.
+.B c
+(cleanup_on_exit) Shut the runtime down gracefully on exit. The option
+also enables pooling (as in caml_startup_pooled). This mode can be used
+to detect leaks with a third-party memory debugger.
 .TP
 .BR h
 The initial size of the major heap (in words).
 .TP
-.BR a \ (allocation_policy)
-The policy used for allocating in the OCaml heap.  Possible values
-are 0 for the next-fit policy, 1 for the first-fit
-policy, and 2 for the best-fit policy. The default is 2.
-See the Gc module documentation for details.
-.TP
-.BR s \ (minor_heap_size)
-The size of the minor heap (in words).
+.BR H
+Allocate heap chunks by mmapping huge pages. Huge pages are locked into
+memory, and are not swapped.
 .TP
 .BR i \ (major_heap_increment)
-The default size increment for the major heap (in words).
-.TP
-.BR o \ (space_overhead)
-The major GC speed setting.
-.TP
-.BR O \ (max_overhead)
-The heap compaction trigger setting.
+The default size increment for the major heap (in words if greater than 1000,
+else in percents of the heap size).
 .TP
 .BR l \ (stack_limit)
 The limit (in words) of the stack size.
 .TP
+.BR m \ (custom_minor_ratio)
+Bound on floating garbage for out-of-heap memory
+held by custom values in the minor heap. A minor GC is triggered
+when this much memory is held by custom values located in the minor
+heap. Expressed as a percentage of minor heap size.
+Note: this only applies to values allocated with
+.B caml_alloc_custom_mem
+(e.g. bigarrays).
+ Default: 100.
+.TP
 .BR M \ (custom_major_ratio)
 Target ratio of floating garbage to
 major heap size for out-of-heap memory held by custom values
@@ -182,16 +195,6 @@ The limit (in words) of the stack size.
 (e.g. bigarrays).
 Default: 44.
 .TP
-.BR m \ (custom_minor_ratio)
-Bound on floating garbage for out-of-heap memory
-held by custom values in the minor heap. A minor GC is triggered
-when this much memory is held by custom values located in the minor
-heap. Expressed as a percentage of minor heap size.
-Note: this only applies to values allocated with
-.B caml_alloc_custom_mem
-(e.g. bigarrays).
- Default: 100.
-.TP
 .BR n \ (custom_minor_max_size)
 Maximum amount of out-of-heap
 memory for each custom value allocated in the minor heap. When a custom
@@ -205,6 +208,32 @@ The limit (in words) of the stack size.
 (e.g. bigarrays).
 Default: 8192 bytes.
 .TP
+.BR o \ (space_overhead)
+The major GC speed setting.
+.TP
+.BR O \ (max_overhead)
+The heap compaction trigger setting.
+.TP
+.B p
+Turn on debugging support for
+.BR ocamlyacc -generated
+parsers.  When this option is on,
+the pushdown automaton that executes the parsers prints a
+trace of its actions.  This option takes no argument.
+.TP
+.BR R
+Turn on randomization of all hash tables by default (see the
+.B Hashtbl
+module of the standard library). This option takes no
+argument.
+.TP
+.BR s \ (minor_heap_size)
+The size of the minor heap (in words).
+.TP
+.B t
+Set the trace level for the debug runtime (ignored by the standard
+runtime).
+.TP
 .BR v \ (verbose)
 What GC messages to print to stderr.  This is a sum of values selected
 from the following:
@@ -242,7 +271,16 @@ Startup messages (loading the bytecode executable file, resolving
 
 .BR 0x400
 Output GC statistics at program exit, in the same format as Gc.print_stat.
+.TP
+.BR w \ (window_size)
+Set size of the window used by major GC for smoothing out variations in
+its workload. This is an integer between 1 and 50. (Default: 1)
+.TP
+.BR W
+Print runtime warnings to stderr (such as Channel opened on file dies without
+being closed, unflushed data, etc.)
 
+.RS 0
 The multiplier is
 .BR k ,
 .BR M ,\ or

manual/src/cmds/runtime.etex

@@ -68,7 +68,8 @@ section~\ref{s:ocamlrun-dllpath}).
 Print the magic number of the bytecode executable given as argument
 and exit.
 \item["-M"]
-Print the magic number expected by this version of the runtime and exit.
+Print the magic number expected for bytecode executables by this version
+of the runtime and exit.
 \item["-p"]
 Print the names of the primitives known to this version of
 "ocamlrun" and exit.
@@ -108,14 +109,19 @@ The following environment variables are also consulted:
   A parameter specification is an option letter followed by an "="
   sign, a decimal number (or an hexadecimal number prefixed by "0x"),
   and an optional multiplier.  The options are documented below;
-  the last six correspond to the fields of the
-  "control" record documented in
+  the options "a, i, l, m, M, n, o, O, s, v, w" correspond to
+  the fields of the "control" record documented in
 \ifouthtml
  \ahref{libref/Gc.html}{Module \texttt{Gc}}.
 \else
  section~\ref{Gc}.
 \fi
   \begin{options}
+  \item[a] ("allocation_policy")
+        The policy used for allocating in the OCaml heap. Possible values
+        are "0" for the next-fit policy, "1" for the first-fit
+        policy, and "2" for the best-fit policy. The default is "2" (best-fit).
+        See the Gc module documentation for details.
   \item[b] (backtrace) Trigger the printing of a stack backtrace
         when an uncaught exception aborts the program. An optional argument can
         be provided: "b=0" turns backtrace printing off; "b=1" is equivalent to
@@ -124,6 +130,46 @@ The following environment variables are also consulted:
         startup time instead of at backtrace printing time. "b=2" can be used if
         the runtime is unable to load debugging information at backtrace
         printing time, for example if there are no file descriptors available.
+  \item[c] ("cleanup_on_exit") Shut the runtime down gracefully on exit (see
+        "caml_shutdown" in section~\ref{ss:c-embedded-code}). The option also enables
+        pooling (as in "caml_startup_pooled"). This mode can be used to detect
+        leaks with a third-party memory debugger.
+  \item[h] The initial size of the major heap (in words).
+  \item[H] Allocate heap chunks by mmapping huge pages. Huge pages are locked into
+        memory, and are not swapped.
+  \item[i] ("major_heap_increment")  Default size increment for the
+        major heap. (in words if greater than 1000, else in percents of the 
+        head size)
+  \item[l] ("stack_limit") The limit (in words) of the stack size. This is only
+        relevant to the byte-code runtime, as the native code runtime uses the
+        operating system's stack.
+  \item[m] ("custom_minor_ratio") Bound on floating garbage for
+        out-of-heap memory
+        held by custom values in the minor heap. A minor GC is triggered
+        when this much memory is held by custom values located in the minor
+        heap. Expressed as a percentage of minor heap size. Default:
+        100. Note: this only applies to values allocated with
+        "caml_alloc_custom_mem".
+  \item[M] ("custom_major_ratio") Target ratio of floating garbage to
+        major heap size for out-of-heap memory held by custom values
+        (e.g. bigarrays) located in the major heap. The GC speed is adjusted
+        to try to use this much memory for dead values that are not yet
+        collected. Expressed as a percentage of major heap size. Default:
+        44. Note: this only applies to values allocated with
+        "caml_alloc_custom_mem".
+  \item[n] ("custom_minor_max_size") Maximum amount of out-of-heap
+        memory for each custom value allocated in the minor heap. When a custom
+        value is allocated on the minor heap and holds more than this many
+        bytes, only this value is counted against "custom_minor_ratio" and
+        the rest is directly counted against "custom_major_ratio".
+        Default: 8192 bytes. Note:
+        this only applies to values allocated with "caml_alloc_custom_mem".
+        \end{options}
+        The multiplier is "k", "M", or "G", for multiplication by $2^{10}$,
+        $2^{20}$, and $2^{30}$ respectively.
+  \item[o] ("space_overhead")  The major GC speed setting.
+        See the Gc module documentation for details.
+  \item[O] ("max_overhead")  The heap compaction trigger setting.
   \item[p] (parser trace) Turn on debugging support for
         "ocamlyacc"-generated parsers.  When this option is on,
         the pushdown automaton that executes the parsers prints a
@@ -136,21 +182,8 @@ The following environment variables are also consulted:
   section~\ref{Hashtbl}).
 \fi
         This option takes no argument.
-  \item[h] The initial size of the major heap (in words).
-  \item[a] ("allocation_policy")
-    The policy used for allocating in the OCaml heap. Possible values
-    are "0" for the next-fit policy, "1" for the first-fit
-    policy, and "2" for the best-fit policy. The default is "2" (best-fit).
-    See the Gc module documentation for details.
   \item[s] ("minor_heap_size")  Size of the minor heap. (in words)
-  \item[i] ("major_heap_increment")  Default size increment for the
-  major heap. (in words)
-  \item[o] ("space_overhead")  The major GC speed setting.
-    See the Gc module documentation for details.
-  \item[O] ("max_overhead")  The heap compaction trigger setting.
-  \item[l] ("stack_limit") The limit (in words) of the stack size. This is only
-  relevant to the byte-code runtime, as the native code runtime uses the
-  operating system's stack.
+  \item[t] Set the trace level for the debug runtime (ignored by the standard runtime).
   \item[v] ("verbose")  What GC messages to print to stderr.  This
   is a sum of values selected from the following:
   \begin{options}
@@ -167,35 +200,11 @@ The following environment variables are also consulted:
         \item[512 (= 0x200)] Computation of compaction-triggering condition.
         \item[1024 (= 0x400)] Output GC statistics at program exit.
   \end{options}
-  \item[c] ("cleanup_on_exit") Shut the runtime down gracefully on exit (see
-  "caml_shutdown" in section~\ref{ss:c-embedded-code}). The option also enables
-  pooling (as in "caml_startup_pooled"). This mode can be used to detect
-  leaks with a third-party memory debugger.
-  % FIXME missing: H, t, w, W see MPR#7870
-  \item[M] ("custom_major_ratio") Target ratio of floating garbage to
-  major heap size for out-of-heap memory held by custom values
-  (e.g. bigarrays) located in the major heap. The GC speed is adjusted
-  to try to use this much memory for dead values that are not yet
-  collected. Expressed as a percentage of major heap size. Default:
-  44. Note: this only applies to values allocated with
-  "caml_alloc_custom_mem".
-  \item[m] ("custom_minor_ratio") Bound on floating garbage for
-  out-of-heap memory
-  held by custom values in the minor heap. A minor GC is triggered
-  when this much memory is held by custom values located in the minor
-  heap. Expressed as a percentage of minor heap size. Default:
-  100. Note: this only applies to values allocated with
-  "caml_alloc_custom_mem".
-  \item[n] ("custom_minor_max_size") Maximum amount of out-of-heap
-  memory for each custom value allocated in the minor heap. When a custom
-  value is allocated on the minor heap and holds more than this many
-  bytes, only this value is counted against "custom_minor_ratio" and
-  the rest is directly counted against "custom_major_ratio".
-  Default: 8192 bytes. Note:
-  this only applies to values allocated with "caml_alloc_custom_mem".
-  \end{options}
-  The multiplier is "k", "M", or "G", for multiplication by $2^{10}$,
-  $2^{20}$, and $2^{30}$ respectively.
+  \item[w] ("window_size") Set the size of the window used by major GC for smoothing out 
+    variations in its workload. This is an integer between 1 and 50. 
+    (Default: 1)
+  \item[W] Print runtime warnings to stderr (such as Channel opened on file 
+    dies without being closed, unflushed data, etc.)
 
   If the option letter is not recognized, the whole parameter is ignored;
   if the equal sign or the number is missing, the value is taken as 1;