Macro ocaml_interop::ocaml_frame

macro_rules! ocaml_frame {
    ($gc:ident nokeep, $body:block) => { ... };
    ($gc:ident, $body:block) => { ... };
}

Opens a new frame inside which new OCaml values can be allocated, and OCaml functions called.

The first argument is the name to which the OCaml frame GC handle will be bound. It will be used to allocate OCaml values and call OCaml functions. Values that result from allocations or function calls using that handle, will have their lifetime bound to it.

The variant ocaml_frame!(gc nokeep, { ... }) (with nokeep after the GC handle variable name) avoids setting up the frame and can be used for blocks that do not keep OCaml pointers alive across OCaml calls (gc.keep(value) cannot be used).

Examples

    ocaml_frame!(gc, { // `gc` gets bound to the frame handle
        let hello_ocaml = &to_ocaml!(gc, "hello OCaml!").keep(gc);
        let bye_ocaml = &to_ocaml!(gc, "bye OCaml!").keep(gc);
        ocaml_call!(print_endline(gc, gc.get(hello_ocaml)));
        ocaml_call!(print_endline(gc, gc.get(bye_ocaml)));
        // Values that don't need to be keept across calls can be used directly
        let immediate_use = to_ocaml!(gc, "no need to `keep` me");
        ocaml_call!(print_endline(gc, immediate_use));
    });

When keep is not needed, a slightly more efficient variant is available by adding the nokeep annotation to the handle variable name. By doing so, no space is reserved for local roots:

    ocaml_frame!(gc nokeep, { // `keep` will not be available
        let ocaml_string = to_ocaml!(gc, "hello OCaml!");
        ocaml_call!(print_endline(gc, ocaml_string));
    });