Document Caml_state_opt

Implement suggestions from Gabriel Scherer and Damien Doligez

Changes

@@ -264,12 +264,15 @@ OCaml 5.0
   Guillaume Munch-Maccagnoni, additional discussions with Stephen
   Dolan and Luc Maranget)
 
-- #5299, #4787, #11138, #11272: `Caml_state` is `NULL` when the domain lock is
-  not held. This allows to test if the current thread holds the lock of its
-  domain, and it makes it simpler to debug when one forgets to acquire
-  the lock.
-  (Guillaume Munch-Maccagnoni, review by Sadiq Jaffer, Xavier Leroy and
-  Gabriel Scherer)
+- #5299, #4787, #11138, #11272, #11506: To help debugging, `Caml_state`
+  now dynamically checks that the domain lock is held, and fails
+  otherwise (with a fatal error at most entry points of the C API, or
+  systematically in debug mode). A new variable `Caml_state_opt` is
+  introduced, and is `NULL` when the domain lock is not held. This
+  allows to test from C code if the current thread holds the lock of
+  its domain.
+  (Guillaume Munch-Maccagnoni, review by Florian Angeletti, Damien
+  Doligez, Sadiq Jaffer, Xavier Leroy, and Gabriel Scherer)
 
 - #11223: The serialization format of custom blocks changed in 4.08,
   but the deserializer would still support the pre-4.08 format.  OCaml

manual/src/cmds/intf-c.etex

@@ -2500,9 +2500,15 @@ CAMLprim stub_gethostbyname(value vname)
 }
 \end{verbatim}
 
-During the time the domain lock is released, the thread-local variable
-"Caml_state" is set to "NULL". This can be used to determine if the
-thread currently holds its domain lock.
+The macro "Caml_state" evaluates to the domain state variable, and
+checks in debug mode that the domain lock is held. Such a check is
+also placed in normal mode at key entry points of the C API; this is
+why calling some of the runtime functions and macros without correctly
+owning the domain lock can result in a fatal error: "no domain lock
+held". The variant "Caml_state_opt" does not perform any check but
+evaluates to "NULL" when the domain lock is not held. This lets you
+determine whether a thread belonging to a domain currently holds its
+domain lock, for various purposes.
 
 Callbacks from C to OCaml must be performed while holding the master
 lock to the OCaml run-time system.  This is naturally the case if the