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

[Alain Frisch <alain@frisch.fr>]

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