Switch to using Boxroot for root handling

[tizoc]

Switching to ocaml-boxroot for roots management.

TODO

• [x] Implement (and use) BoxRoot
• [x] Remove to_ocaml!, ocaml_frame!, etc (no longer needed macros)
• [x] Update tests
• [x] Finish updating documentation (remove outdated stuff, explain OCaml/Boxroot/OCamlRef, etc)
• [x] Update CHANGELOG

[tizoc]

@g2p here is the WIP work on boxroots integration, I don't think the code will change much more, but I still have to finish the docs.

[tizoc]

pub fn make_some(cr: &mut OCamlRuntime, value: String) -> Option<String> {
    ocaml_frame!(cr, (root), {
        let str = to_ocaml!(cr, value, root); // `OCamlRef<String>`
        let result = ocaml::make_some(cr, str);
        result.to_rust()
    })
}

should now be written as:

pub fn make_some(cr: &mut OCamlRuntime, value: String) -> Option<String> {
    let str = value.to_ocaml_rooted(cr); // BoxRoot<String>
    let result = ocaml::make_some(cr, &str); // dereferenced into `OCamlRef<String>`
    result.to_rust(cr)
}

To note:

• ocaml_frame! macro is gone
• to_ocaml! macro is gone
• New to_ocaml_rooted method in the ToOCaml trait, which is the same as to_ocaml but returns a rooted value (a BoxRoot<T> instead of an OCaml<'gc, T>.

This BoxRoot<T> is an owned root, it can be passed around (not bound to the stack lifetime like local roots). Once dropped will delete the root on the OCaml side so that the pointed-to value can be collected. An OCaml<'gc, T> value can be recovered with cr.get(boxroot), and boxroots also deref into OCamlRef<T> references that are what OCaml functions expect as inputs.

[tizoc]

cc @zshipko

[zshipko]

Cool! I will create a new ocaml-rs branch later today to start integrating these changes

[tizoc]

Still unsure about the name to_ocaml_rooted, too long and ugly, considering to_boxroot.