From 9d4faca7af8d9849093ff8d36509ad60608ac239 Mon Sep 17 00:00:00 2001
From: Xavier Leroy <xavierleroy@users.noreply.github.com>
Date: Thu, 7 Jul 2022 18:22:22 +0200
Subject: [PATCH 11/24] Document limitation on `caml_callbackN` (#11409)
The `args` argument array must not be declared with `CAMLlocalN`, otherwise
the array can be registered a second time by `caml_callbackN`, confusing
the compactor.
Also: suggests using a C99 compound literal, it looks good and avoids the issue.
Fixes: #11045
---
Changes | 7 +++++++
manual/src/cmds/intf-c.etex | 4 ++++
2 files changed, 11 insertions(+)
diff --git a/Changes b/Changes
index 8182f5ced7..13eb7fef98 100644
--- a/Changes
+++ b/Changes
@@ -25,6 +25,13 @@ OCaml 4.14 maintenance branch
- #11392, #11392: assertion failure with -rectypes and external definitions
(Gabriel Scherer, review by Florian Angeletti, report by Dmitrii Kosarev)
+### Manual and documentation:
+
+- #11045, #11409: document that the array argument to `caml_callbackN`
+ must not have been declared by `CAMLlocalN`.
+ (Xavier Leroy, report by Stephen Dolan, review by Gabriel Scherer.)
+
+
OCaml 4.14.0 (28 March 2022)
----------------------------
diff --git a/manual/src/cmds/intf-c.etex b/manual/src/cmds/intf-c.etex
index 7cd50a1372..bb420c2940 100644
--- a/manual/src/cmds/intf-c.etex
+++ b/manual/src/cmds/intf-c.etex
@@ -1449,6 +1449,10 @@ the value \var{a} and returns the value returned by~\var{f}.
(a curried OCaml function with three arguments) to \var{a}, \var{b} and \var{c}.
\item "caml_callbackN("\var{f, n, args}")" applies the functional value \var{f}
to the \var{n} arguments contained in the C array of values \var{args}.
+The array \var{args} must \emph{not} be declared with "CAMLlocalN".
+It should be declared as "value "\var{args}"["\var{n}"];".
+Alternatively, a C99 compound literal can be used:
+"caml_callbackN("\var{f, n, }"(value[]){"\nth{arg}{1}, \ldots, \nth{arg}{n}"})".
\end{itemize}
If the function \var{f} does not return, but raises an exception that
escapes the scope of the application, then this exception is
--
2.37.0.rc2