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

[Marek Kubica <marek@xivilization.net>]

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