OCaml 5 on runtime4: manual changes (#219)

* [BACKPORT] Adapt to 4.14 runtime

(cherry picked from commit f8a3f2aae8aacfddeeecdc2cc8d3d2152bc28175)

* [BACKPORT] Adapt to 4.14 runtime

(cherry picked from commit ace0fdc943180e114a1d99f3e51f5c73693deaf9)

---------

Co-authored-by: David Allsopp <[email protected]>

Author: mshinwell

manual/src/refman/extensions/effects.etex

@@ -24,7 +24,7 @@ To understand the basics, let us define an effect (that is, an operation) that
 takes an integer argument and returns an integer result. We name this effect
 "Xchg".
 
-\begin{caml_example*}{verbatim}
+\begin{caml_example*}{verbatim}[error]
 open Effect
 open Effect.Deep
 
@@ -42,7 +42,7 @@ returns their sum.
 We can handle the "Xchg" effect by implementing a handler that always returns
 the successor of the offered value:
 
-\begin{caml_example}{verbatim}
+\begin{caml_example}{verbatim}[error]
 try_with comp1 ()
 { effc = fun (type a) (eff: a t) ->
     match eff with
@@ -99,7 +99,7 @@ computations \textit{tasks}.
 A task either is in a suspended state or is completed. We represent the task
 status as follows:
 
-\begin{caml_example*}{verbatim}
+\begin{caml_example*}{verbatim}[error]
 type 'a status =
   Complete of 'a
 | Suspended of {msg: int; cont: (int, 'a status) continuation}
@@ -113,7 +113,7 @@ resume and returns a "'a status" value when resumed.
 Next, we define a "step" function that executes one step of computation until
 it completes or suspends:
 
-\begin{caml_example*}{verbatim}
+\begin{caml_example*}{verbatim}[error]
 let step (f : unit -> 'a) () : 'a status =
   match_with f ()
   { retc = (fun v -> Complete v);
@@ -156,7 +156,7 @@ the status does not perform the "Xchg" effect.
 
 We can now write a simple scheduler that runs a pair of tasks to completion:
 
-\begin{caml_example*}{verbatim}
+\begin{caml_example*}{verbatim}[error]
 let rec run_both a b =
   match a (), b () with
   | Complete va, Complete vb -> (va, vb)
@@ -175,13 +175,13 @@ the handler to raise an exception
 
 We can now define a second computation that also exchanges two messages:
 
-\begin{caml_example*}{verbatim}
+\begin{caml_example*}{verbatim}[error]
 let comp2 () = perform (Xchg 21) * perform (Xchg 21)
 \end{caml_example*}
 
 Finally, we can run the two computations together:
 
-\begin{caml_example}{verbatim}
+\begin{caml_example}{verbatim}[error]
 run_both (step comp1) (step comp2)
 \end{caml_example}
 
@@ -202,7 +202,7 @@ user-level threading systems provide a "fork" primitive to spawn off a new
 concurrent task and a "yield" primitive to yield control to some other task.
 Correspondingly, we shall declare two effects as follows:
 
-\begin{caml_example*}{verbatim}
+\begin{caml_example*}{verbatim}[error]
 type _ Effect.t += Fork : (unit -> unit) -> unit t
                  | Yield : unit t
 \end{caml_example*}
@@ -215,15 +215,15 @@ also offering to exchange a value.
 
 We shall also define helper functions that simply perform these effects:
 
-\begin{caml_example*}{verbatim}
+\begin{caml_example*}{verbatim}[error]
 let fork f = perform (Fork f)
 let yield () = perform Yield
 let xchg v = perform (Xchg v)
 \end{caml_example*}
 
 A top-level "run" function defines the scheduler:
 
-\begin{caml_example*}{verbatim}
+\begin{caml_example*}{verbatim}[error]
 (* A concurrent round-robin scheduler *)
 let run (main : unit -> unit) : unit =
   let exchanger = ref None in (* waiting exchanger *)
@@ -296,7 +296,7 @@ explain and fix this in the next section~\ref{s:effects-discontinue}.
 Now we can write a concurrent program that utilises the newly defined
 operations:
 
-\begin{caml_example}{verbatim}
+\begin{caml_example}{verbatim}[error]
 open Printf
 
 let _ = run (fun _ ->
@@ -341,7 +341,7 @@ exchange a value (stored in the reference cell "exchanger"), which remains
 blocked forever! If the blocked task holds onto resources, these resources are
 leaked. For example, consider the following task:
 
-\begin{caml_example*}{verbatim}
+\begin{caml_example*}{verbatim}[error]
 let leaky_task () =
   fork (fun _ ->
     let oc = open_out "secret.txt" in
@@ -442,7 +442,7 @@ lst_iter (fun i -> Printf.printf "%d\n" i)
 The expression "invert lst_iter" returns a sequence that allows the consumer to
 traverse the list on demand. For example,
 
-\begin{caml_example}{verbatim}
+\begin{caml_example}{verbatim}[error]
 let s = invert ~iter:lst_iter
 let next = Seq.to_dispenser s;;
 next();;
@@ -453,7 +453,7 @@ next();;
 
 We can use the same "invert" function on any "iter" function. For example,
 
-\begin{caml_example}{verbatim}
+\begin{caml_example}{verbatim}[error]
 let s = invert ~iter:(Fun.flip String.iter "OCaml")
 let next = Seq.to_dispenser s;;
 next();;
@@ -468,7 +468,7 @@ next();;
 
 The implementation of the "invert" function is given below:
 
-\begin{caml_example*}{verbatim}
+\begin{caml_example*}{verbatim}[error]
 let invert (type a) ~(iter : (a -> unit) -> unit) : a Seq.t =
   let module M = struct
     type _ Effect.t += Yield : a -> unit t
@@ -517,7 +517,7 @@ examples.
 
 Like exception handlers, effect handlers can be nested.
 
-\begin{caml_example*}{verbatim}
+\begin{caml_example*}{verbatim}[error]
 type _ Effect.t += E : int t
                  | F : string t
 
@@ -544,7 +544,7 @@ In this example, the computation "foo" performs "F", the inner handler handles
 only "E" and the outer handler handles "F". The call to "baz" returns "Hello,
 world!".
 
-\begin{caml_example}{verbatim}
+\begin{caml_example}{verbatim}[error]
 baz ()
 \end{caml_example}
 
@@ -606,7 +606,7 @@ corresponding "perform". For example, in the previous example, "bar" does not
 handle the effect "F". Hence, we will get an "Effect.Unhandled F" exception
 when we run "bar".
 
-\begin{caml_example}{verbatim}
+\begin{caml_example}{verbatim}[error]
 try bar () with Effect.Unhandled F -> "Saw Effect.Unhandled exception"
 \end{caml_example}
 
@@ -618,7 +618,7 @@ must be resumed either with a "continue" or "discontinue" exactly once}}.
 Attempting to use a continuation more than once raises a
 "Continuation_already_resumed" exception. For example:
 
-\begin{caml_example}{verbatim}
+\begin{caml_example}{verbatim}[error]
 try_with perform (Xchg 0)
 { effc = fun (type a) (eff : a t) ->
     match eff with
@@ -685,7 +685,7 @@ implement a shallow handler that enforces a particular sequence of effects (a
 protocol) on a computation. For this example, let us consider that the
 computation may perform the following effects:
 
-\begin{caml_example*}{verbatim}
+\begin{caml_example*}{verbatim}[error]
 type _ Effect.t += Send : int -> unit Effect.t
                  | Recv : int Effect.t
 \end{caml_example*}
@@ -698,7 +698,7 @@ not "[Recv]", "[Send;Send]", "[Send;Recv;Recv]", etc. The key observation here
 is that the set of effects handled evolves over time. We can enforce this
 protocol quite naturally using shallow handlers as shown below:
 
-\begin{caml_example*}{verbatim}
+\begin{caml_example*}{verbatim}[error]
 open Effect.Shallow
 
 let run (comp: unit -> unit) : unit =
@@ -753,7 +753,7 @@ be handled by an outer handler.
 We can see that the "run" function will permit a computation that follows the
 protocol:
 
-\begin{caml_example}{verbatim}
+\begin{caml_example}{verbatim}[error]
 run (fun () ->
   printf "Send 42\n";
   perform (Send 42);
@@ -765,7 +765,7 @@ run (fun () ->
 
 and aborts those that do not:
 
-\begin{caml_example}{verbatim}
+\begin{caml_example}{verbatim}[error]
 run (fun () ->
   Printf.printf "Send 0\n";
   perform (Send 0);

manual/src/tutorials/memorymodel.etex

@@ -25,7 +25,7 @@ can be explained through some interleaving of the operations from different
 domains in the program. For example, consider the following program with two
 domains "d1" and "d2" executing in parallel:
 
-\begin{caml_example*}{verbatim}
+\begin{caml_example*}{verbatim}[error]
 let d1 a b =
   let r1 = !a * 2 in
   let r2 = !b in
@@ -52,7 +52,7 @@ of the operations from different domains.
 
 Let us now assume that "a" and "b" are aliases of each other.
 
-\begin{caml_example*}{verbatim}
+\begin{caml_example*}{verbatim}[error]
 let d1 a b =
   let r1 = !a * 2 in
   let r2 = !b in
@@ -83,7 +83,7 @@ Surprisingly, this assertion may fail in OCaml due to compiler optimisations.
 The OCaml compiler observes the common sub-expression "!a * 2" in "d1" and
 optimises the program to:
 
-\begin{caml_example*}{verbatim}
+\begin{caml_example*}{verbatim}[error]
 let d1 a b =
   let r1 = !a * 2 in
   let r2 = !b in
@@ -138,7 +138,7 @@ location respect sequential consistency, the guarantees on programs that
 operate on different memory locations are much weaker. Consider the following
 program:
 
-\begin{caml_example*}{verbatim}
+\begin{caml_example*}{verbatim}[error]
 let a = ref 0
 and b = ref 0
 
@@ -660,7 +660,7 @@ B: 5,  [a -> t2; b -> t4; c -> t6]
 
 Let us revisit an example from earlier (section \ref{s:why_relaxed_memory}).
 
-\begin{caml_example*}{verbatim}
+\begin{caml_example*}{verbatim}[error]
 let a = ref 0
 and b = ref 0
 

manual/src/tutorials/parallelism.etex

@@ -27,7 +27,7 @@ Domains are the units of parallelism in OCaml. The module \stdmoduleref{Domain}
 provides the primitives to create and manage domains. New domains can be
 spawned using the "spawn" function.
 
-\begin{caml_example}{verbatim}
+\begin{caml_example}{verbatim}[error]
 Domain.spawn (fun _ -> print_endline "I ran in parallel")
 \end{caml_example}
 
@@ -90,7 +90,7 @@ Spawned domains can be joined using the "join" function to get their results.
 The "join" function waits for target domain to terminate. The following program
 computes the nth Fibonacci number twice in parallel.
 
-\begin{caml_example*}{verbatim}
+\begin{caml_example*}{verbatim}[error]
 (* fib_twice.ml *)
 let n = int_of_string Sys.argv.(1)
 
@@ -132,7 +132,7 @@ Let us attempt to parallelise the Fibonacci function. The two recursive calls
 may be executed in parallel. However, naively parallelising the recursive calls
 by spawning domains for each one will not work as it spawns too many domains.
 
-\begin{caml_example}{verbatim}
+\begin{caml_example}{verbatim}[error]
 (* fib_par1.ml *)
 let n = try int_of_string Sys.argv.(1) with _ -> 1
 
@@ -468,7 +468,7 @@ rest of this chapter, we shall call the threads created by the threads library
 as \emph{systhreads}. The following program implements a concurrent stack using
 mutex and condition variables.
 
-\begin{caml_example*}{verbatim}
+\begin{caml_example*}{verbatim}[error]
 module Blocking_stack : sig
   type 'a t
   val make : unit -> 'a t
@@ -615,7 +615,7 @@ often compiled to atomic read-modify-write primitives that the hardware
 provides. As an example, the following program increments a non-atomic counter
 and an atomic counter in parallel.
 
-\begin{caml_example*}{verbatim}
+\begin{caml_example*}{verbatim}[error]
 (* incr.ml *)
 let twice_in_parallel f =
   let d1 = Domain.spawn f in
@@ -672,7 +672,7 @@ The atomic variables can be used for low-level synchronisation between the
 domains. The following example uses an atomic variable to exchange a message
 between two domains.
 
-\begin{caml_example}{verbatim}
+\begin{caml_example}{verbatim}[error]
 let r = Atomic.make None
 
 let sender () = Atomic.set r (Some "Hello")
@@ -699,7 +699,7 @@ race since "r" is an atomic reference.
 The Atomic module is used to implement non-blocking, lock-free data structures.
 The following program implements a lock-free stack.
 
-\begin{caml_example*}{verbatim}
+\begin{caml_example*}{verbatim}[error]
 module Lockfree_stack : sig
   type 'a t
   val make : unit -> 'a t