[Caml-list] OCaml C macros, what do they do?

[Caml-list] OCaml C macros, what do they do?

[Marek Kubica]

Hi,

I've been using the OCaml C API lately with quite some success (after I
realized that the GC causes everything to crash and fixing a lot of
stuff).

While things work now quite well, I'd like to know what *exactly* the
macros are for, since sometimes I can leave them out without any ill
effect.

So, here's my insights. If anyone of you could point out what is
correct and what is not, I'd be grateful:

 - CAMLparam1(foo), notifies the GC that foo is used in this function
   and not to be collected.
 - CAMLlocal1(foo), creates a local variable foo. This is only required
   if I want to bind some "value" type to a variable name. Not required
   if I immediately return it.
 - CAMLreturn(foo) returns a foo value and tells the GC that everything
   declared by CAMLparam will not be used anymore and could be
   collected.
 - CAMLprim defines a function as "primitive" according to the
   documentation. I have no idea what that means. The example in the
   manual, section 19.6 does not use CAMLprim to start with.

regards,
Marek

Re: [Caml-list] OCaml C macros, what do they do?

[Alain Frisch]

On 04/10/2013 06:15 PM, Marek Kubica wrote:
>   - CAMLparam1(foo), notifies the GC that foo is used in this function
>     and not to be collected.

And also that the foo pointer must be updated if the corresponding block 
is moved by the GC.  So even if you can guarantee that foo will not be 
collected (because it is accessible otherwise), you must use CAMLparam 
if there is a possibility that the GC will be triggered in the function.

>   - CAMLlocal1(foo), creates a local variable foo. This is only required
>     if I want to bind some "value" type to a variable name. Not required
>     if I immediately return it.

Same as above.  All local values holding OCaml values that can be blocks 
(not only "ints") must reside in variables marked as CAMLlocal/CAMLparam 
at the time a GC occurs.  In particular, it is generally unsafe to chain 
function calls without putting the intermediate result in a local 
variable marked as CAMLlocal.

>   - CAMLreturn(foo) returns a foo value and tells the GC that everything
>     declared by CAMLparam will not be used anymore and could be
>     collected.

Yes.

>   - CAMLprim defines a function as "primitive" according to the
>     documentation. I have no idea what that means. The example in the
>     manual, section 19.6 does not use CAMLprim to start with.

AFAIK, CAMLprim is only used within the OCaml distribution itself to 
collect (with sed) names of builtin primitives to be exposed by default 
by ocamlrun to bytecode programs.


-- Alain

Re: [Caml-list] OCaml C macros, what do they do?

[Marek Kubica]

Hello Alain,

Thanks for your answer, I'm glad that I was not so far off and can see
clearer now.

On Wed, 10 Apr 2013 19:05:06 +0200
Alain Frisch <alain@frisch.fr> wrote:

> On 04/10/2013 06:15 PM, Marek Kubica wrote:
> >   - CAMLparam1(foo), notifies the GC that foo is used in this
> > function and not to be collected.
> 
> And also that the foo pointer must be updated if the corresponding
> block is moved by the GC.  So even if you can guarantee that foo will
> not be collected (because it is accessible otherwise), you must use
> CAMLparam if there is a possibility that the GC will be triggered in
> the function.

If I understand correctly, GC is only triggered by the caml_*
allocation functions, or is there some other possibility that I am
missing?

> >   - CAMLlocal1(foo), creates a local variable foo. This is only
> > required if I want to bind some "value" type to a variable name.
> > Not required if I immediately return it.
> 
> Same as above.  All local values holding OCaml values that can be
> blocks (not only "ints") must reside in variables marked as
> CAMLlocal/CAMLparam at the time a GC occurs.  In particular, it is
> generally unsafe to chain function calls without putting the
> intermediate result in a local variable marked as CAMLlocal.

Okay, I suspected so much but wasn't sure since when I tried chaining
without CAMLlocal it worked. But an edge case might require it. I'll
add CAMLlocals to my code to be on the safe side, thanks.

> AFAIK, CAMLprim is only used within the OCaml distribution itself to 
> collect (with sed) names of builtin primitives to be exposed by
> default by ocamlrun to bytecode programs.

Great, so it doesn't apply to my code at all. Will remove it.

regards,
Marek