[Caml-list] Auxiliary C function which manipulates the OCaml heap

[Caml-list] Auxiliary C function which manipulates the OCaml heap

[Romain Bardou]

Hello,

I have a C function "aux" which may either:
- raise an OCaml exception with caml_raise_with_arg;
- return void.

The argument of caml_raise_with_arg is allocated in "aux". So I should 
be careful and declare it to the GC. I do so using CAMLlocal.

However, this function does not use CAMLreturn, as it does not return an 
OCaml value but a C value (actually void). So the compiler emits a 
warning: "unused variable 'caml__frame'" if I use CAMLparam in aux.

Is it ok to call CAMLlocal in this way? The documentation says it cannot 
be called inside nested blocks. Is an auxiliary function considered a 
nested block?

Note that the caller of "aux", or (in another case) the caller of the 
caller of "aux", has called CAMLparam. If this was not the case, would 
it make a difference?

Similarly, if "aux" had some OCaml value arguments, should it call 
CAMLparam even though the caller of "aux" has declared them to the GC 
using CAMLparam or CAMLlocal?

Similarly, if "aux" did return an OCaml value, should it call CAMLreturn 
(and thus CAMLparam) to return the value, or should it use the normal 
"return"?

Thanks,

-- 
Romain Bardou

Re: [Caml-list] Auxiliary C function which manipulates the OCaml heap

[Jeremie Dimino]

Hi,

On Tue, Mar 12, 2013 at 2:54 PM, Romain Bardou <romain.bardou@inria.fr> wrote:
> However, this function does not use CAMLreturn, as it does not return an
> OCaml value but a C value (actually void). So the compiler emits a warning:
> "unused variable 'caml__frame'" if I use CAMLparam in aux.
>
> Is it ok to call CAMLlocal in this way? The documentation says it cannot be
> called inside nested blocks. Is an auxiliary function considered a nested
> block?

No, you must use [CAMLreturn0] in this case.

> Note that the caller of "aux", or (in another case) the caller of the caller
> of "aux", has called CAMLparam. If this was not the case, would it make a
> difference?

No, CAMLparam macros are only for the current function.  They register
the C local variables as local roots.  In sub-function they are
different local variables (different position on the stack) so you
need to register them too.

> Similarly, if "aux" had some OCaml value arguments, should it call CAMLparam
> even though the caller of "aux" has declared them to the GC using CAMLparam
> or CAMLlocal?

Yes.

> Similarly, if "aux" did return an OCaml value, should it call CAMLreturn
> (and thus CAMLparam) to return the value, or should it use the normal
> "return"?

You must use [CAMLreturnT(C-type, expr)] in this case.

And for other cases you can also use Begin_roots and End_roots.