TMC manual: be explicit about the OCaml 5 different situation

1 files changed, 25 insertions, 0 deletions

diff --git a/manual/src/cmds/tail-mod-cons.etex b/manual/src/cmds/tail-mod-cons.etex
index 12806459a2..f4ae7f04e8 100644
--- a/manual/src/cmds/tail-mod-cons.etex
+++ b/manual/src/cmds/tail-mod-cons.etex
@@ -158,6 +158,31 @@ tail-mod-cons are as follows:
   using a convenient monadic notation.
 \end{itemize}
 
+\paragraph{Note: OCaml call stack size} Under OCaml 4, bytecode
+programs respect the "stack_limit" runtime parameter configuration
+(as set using "Gc.set" in the example above), or the "l" setting of
+the "OCAMLRUNPARAM" variable. Native programs ignore these settings
+and only respect the operating system native stack limit, as set by
+"ulimit" on Unix systems. Most operating systems run with a relatively
+low stack size limit by default, so Stack Overflow on
+non-tail-recursive functions are a common programming bug.
+
+Under OCaml 5, native code does not use the native system stack for
+OCaml function calls anymore, so it is not affected by the operating
+system native stack size; both native and bytecode programs respect
+the OCaml runtime's own limit. The runtime limit is set to a much
+higher default than most operating system native stacks, so we expect
+Stack Overflow occurrences to be much less common in
+practice. (We still have a stack limit by default, as they remain
+useful to quickly catch bugs with looping non-tail-recursive
+functions. Without a stack limit you would have instead to wait for
+them to eat your whole memory, which can take a while.)
+
+This means that the "tail modulo constructor" transformation is less
+important on OCaml 5: it does improve performance noticeably in some
+cases, but it is not necessary for basic correctness for most
+use-cases.
+
 \section{sec:disambiguation}{Disambiguation}
 
 It may happen that several arguments of a constructor are recursive