Crate ocaml_interop

Source

Expand description

Zinc-iron alloy coating is used in parts that need very good corrosion protection.

API IS CONSIDERED UNSTABLE AT THE MOMENT AND IS LIKELY TO CHANGE IN THE FUTURE

IMPORTANT: Starting with version 0.11.0 only OCaml 5.x is supported

ocaml-interop is an OCaml<->Rust FFI with an emphasis on safety inspired by caml-oxide, ocaml-rs and CAMLroot.

§Usage

This section provides a high-level overview of ocaml-interop. For detailed explanations, tutorials, and best practices, please refer to the User Guides module.

§Runtime Initialization and Management

Proper initialization and management of the OCaml runtime is crucial, especially when Rust code drives the execution. This involves using OCamlRuntime::init and managing its lifecycle with OCamlRuntimeStartupGuard.

For detailed information, see OCaml Runtime (Part 5).

§Acquiring and Using the OCaml Runtime Handle

Most interop operations require an OCaml runtime handle (cr: &mut OCamlRuntime). This handle is obtained differently depending on whether Rust calls OCaml or OCaml calls Rust.

See these guides for more details:

§OCaml value representation

OCaml values are represented in Rust using types like OCaml<'gc, T>, BoxRoot<T>, and OCamlRef<'a, T>, each with specific roles in memory management and GC interaction.

Learn more in Part 2: Fundamental Concepts.

§Converting between OCaml and Rust data

The traits FromOCaml and ToOCaml facilitate data conversion between Rust and OCaml types.

For conversion details and examples, refer to Part 2: Fundamental Concepts, as well as the guides on exporting and invoking functions.

§Calling convention

ocaml-interop uses a caller-rooted argument convention for safety, where the caller is responsible for ensuring arguments are rooted before a function call.

This is explained further in Part 2: Fundamental Concepts.

§OCaml exceptions

By default, Rust panics in exported functions are caught and translated to OCaml exceptions. Conversely, OCaml exceptions raised during calls from Rust will result in Rust panics.

For error handling strategies, see Part 2: Fundamental Concepts and Part 6: Advanced Topics.

§Calling into OCaml from Rust

To call OCaml functions from Rust, they typically need to be registered in OCaml (e.g., using Callback.register) and then declared in Rust using the ocaml! macro. This setup allows Rust to find and invoke these OCaml functions.

For a comprehensive guide on calling OCaml functions from Rust, including detailed examples and best practices, please see: Invoking OCaml Functions (Part 4).

§Calling into Rust from OCaml

Rust functions can be exposed to OCaml using the #[ocaml_interop::export] procedural macro, which handles FFI boilerplate, type marshalling, and panic safety.

Attributes like no_panic_catch, bytecode, and noalloc allow customization.

For a detailed guide, see Exporting Rust Functions (Part 3).

§References and links

OCaml Manual: Chapter 20 Interfacing C with OCaml.
Safely Mixing OCaml and Rust paper by Stephen Dolan.
Safely Mixing OCaml and Rust talk by Stephen Dolan.
CAMLroot: revisiting the OCaml FFI.
caml-oxide, the code from that paper.
ocaml-rs, another OCaml<->Rust FFI library.

Modules§

bigarray
user_guides: ocaml-interop: OCaml and Rust Integration

Macros§

impl_conv_ocaml_record: Implements conversion between a Rust struct and an OCaml record.
impl_conv_ocaml_variant: Implements conversion between a Rust enum and an OCaml variant.
impl_from_ocaml_polymorphic_variant: Implements FromOCaml for mapping an OCaml polymorphic variant into a Rust enum.
impl_from_ocaml_record: Implements FromOCaml for mapping an OCaml record into a Rust record.
impl_from_ocaml_variant: Implements FromOCaml for mapping an OCaml variant into a Rust enum.
impl_to_ocaml_polymorphic_variant: Implements ToOCaml for mapping a Rust enum into an OCaml polymorphic variant.
impl_to_ocaml_record: Implements ToOCaml for mapping a Rust record into an OCaml record.
impl_to_ocaml_variant: Implements ToOCaml for mapping a Rust enum into an OCaml variant.
ocaml: Declares OCaml functions.
ocaml_alloc_polymorphic_variant: Allocates an OCaml polymorphic variant, mapped from a Rust enum.
ocaml_alloc_record: Allocates an OCaml record built from a Rust record
ocaml_alloc_tagged_block: Allocates an OCaml memory block tagged with the specified value.
ocaml_alloc_variant: Allocates an OCaml variant, mapped from a Rust enum.
ocaml_unpack_polymorphic_variant: Unpacks an OCaml polymorphic variant and maps it into a Rust enum.
ocaml_unpack_record: Unpacks an OCaml record into a Rust record.
ocaml_unpack_variant: Unpacks an OCaml variant and maps it into a Rust enum.

Structs§

BoxRoot: BoxRoot<T> is a container for a rooted OCaml<T> value.
DynBox: OCaml<DynBox<T>> is for passing a value of type T to OCaml
OCaml: Representation of OCaml values.
OCamlBytes: OCaml<OCamlBytes> is a reference to an OCaml bytes value.
OCamlException: OCaml<OCamlException> is a reference to an OCaml exn value.
OCamlFloat: OCaml<OCamlFloat> is a reference to an OCaml float (boxed float) value.
OCamlFloatArray: OCaml<OCamlFloatArray<T>> is a reference to an OCaml floatarray which is an array containing floats in an unboxed form.
OCamlInt32: OCaml<OCamlInt32> is a reference to an OCaml Int32.t (boxed int32) value.
OCamlInt64: OCaml<OCamlInt64> is a reference to an OCaml Int64.t (boxed int64) value.
OCamlList: OCaml<OCamlList<T>> is a reference to an OCaml list containing values of type T.
OCamlRuntime: Per-thread handle to the OCaml runtime.
OCamlRuntimeStartupGuard: RAII guard for the OCaml runtime.
OCamlUniformArray: OCaml<OCamlUniformArray<T>> is a reference to an OCaml array which is guaranteed to not contain unboxed floats. If OCaml was configured with --disable-flat-float-array this corresponds to regular arrays, but if not, Uniform_array.t in the base library can be used instead. See Lexifi’s blog post on the topic for more details.

Traits§

FromOCaml: Implements conversion from OCaml values into Rust values.
ToOCaml: Implements conversion from Rust values into OCaml values.

Functions§

alloc_error
alloc_ok
cons: List constructor

Type Aliases§

OCamlFn1: OCaml function that accepts one argument.
OCamlFn2: OCaml function that accepts two arguments.
OCamlFn3: OCaml function that accepts three arguments.
OCamlFn4: OCaml function that accepts four arguments.
OCamlFn5: OCaml function that accepts five arguments.
OCamlInt: OCaml<OCamlInt> is an OCaml integer (tagged and unboxed) value.
OCamlRef: An OCamlRef<T> is a reference to a location containing a OCaml<T> value.
RawOCaml: OCaml value type

Attribute Macros§

export: Exports a Rust function to OCaml.

Crate ocaml_interopCopy item path