From 9acf32acf8843db4083c92a0200309fa51d0e4d1 Mon Sep 17 00:00:00 2001 From: Xavier Leroy Date: Thu, 7 Jul 2022 18:22:22 +0200 Subject: [PATCH] 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 8182f5ced7a0..13eb7fef986d 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 7cd50a1372b6..bb420c2940ea 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