Merge pull request #11813 from edwintorok/5.0-docs

5.0 docs: Make new multicore chapters easier to discover, and emphasize impact on C bindings

(cherry picked from commit 5f856479c79900c42525543677609b78a2032131)

2 files changed, 11 insertions, 0 deletions

diff --git a/manual/src/cmds/intf-c.etex b/manual/src/cmds/intf-c.etex
index d1473fcf09..fcdaf2453c 100644
--- a/manual/src/cmds/intf-c.etex
+++ b/manual/src/cmds/intf-c.etex
@@ -2433,6 +2433,7 @@ When OCaml calls the C code implementing a primitive, the domain lock
 is held, therefore the C code has full access to the facilities of the
 run-time system.  However, no other thread in the same domain can execute
 OCaml code concurrently with the C code of the primitive.
+See also chapter~\ref{s:par_c_bindings} for the behaviour with multiple domains.
 
 If a C primitive runs for a long time or performs potentially blocking
 input-output operations, it can explicitly release the domain lock,
diff --git a/manual/src/tutorials/parallelism.etex b/manual/src/tutorials/parallelism.etex
index 127335b8ab..1d41cb9035 100644
--- a/manual/src/tutorials/parallelism.etex
+++ b/manual/src/tutorials/parallelism.etex
@@ -594,6 +594,16 @@ systhread identifiers uniquely identify systhreads in the program. The initial
 domain gets the domain id and the thread id as 0. The newly spawned domain gets
 domain id as 1.
 
+\section{s:par_c_bindings}{Interaction with C bindings}
+
+During parallel execution with multiple domains, C code running on a domain may
+run in parallel with any C code running in other domains even if neither of
+them has released the ``domain lock''. Prior to OCaml 5.0, C bindings may have
+assumed that if the OCaml runtime lock is not released, then it would be safe
+to manipulate global C state (e.g. initialise a function-local static value).
+This is no longer true in the presence of parallel execution with multiple
+domains.
+
 \section{s:par_atomics}{Atomics}
 
 Mutex, condition variables and semaphores are used to implement blocking