Crate ocaml

ocaml-rs is a library for directly interacting with the C OCaml runtime, in Rust.

The OCaml manual chapter Interfacing C with OCaml does a great job of explaining low-level details about how to safely interact with the OCaml runtime. This crate aims to be a slightly higher-level of abstraction, with minimal added overhead.

Getting started

Take a look at the ocaml-rust-starter project for a basic example to help get started with ocaml-rs.

Examples

// Automatically derive `IntoValue` and `FromValue`
#[cfg(feature = "derive")]
#[derive(ocaml::IntoValue, ocaml::FromValue)]
struct Example {
    name: String,
    i: ocaml::Int,
}

#[cfg(feature = "derive")]
#[ocaml::func]
pub fn incr_example(mut e: Example) -> Example {
    e.i += 1;
    e
}

#[cfg(feature = "derive")]
#[ocaml::func]
pub fn build_tuple(i: ocaml::Int) -> (ocaml::Int, ocaml::Int, ocaml::Int) {
    (i + 1, i + 2, i + 3)
}

/// A name for the garbage collector handle can also be specified:
#[cfg(feature = "derive")]
#[ocaml::func(my_gc_handle)]
pub unsafe fn my_string() -> ocaml::Value {
    ocaml::Value::string("My string")
}

#[cfg(feature = "derive")]
#[ocaml::func]
pub fn average(arr: ocaml::Array<f64>) -> Result<f64, ocaml::Error> {
    let mut sum = 0f64;

    for i in 0..arr.len() {
        sum += arr.get_double(i)?;
    }

    Ok(sum / arr.len() as f64)
}

// A `native_func` must take `ocaml::Value` for every argument or `f64` for
// every unboxed argument and return an `ocaml::Value` (or `f64`).
// `native_func` has minimal overhead compared to wrapping with `func`
#[cfg(feature = "derive")]
#[ocaml::native_func]
pub unsafe fn incr(value: ocaml::Value) -> ocaml::Value {
    let i = value.int_val();
    ocaml::Value::int(i + 1)
}

// This is equivalent to:
#[no_mangle]
pub unsafe extern "C" fn incr2(value: ocaml::Value) -> ocaml::Value {
    ocaml::body!(gc: {
        let i = value.int_val();
        ocaml::Value::int( i + 1)
    })
}

// `ocaml::native_func` is responsible for:
// - Ensures that #[no_mangle] and extern "C" are added, in addition to wrapping
// - Wraps the function body using `ocaml::body!`

// Finally, if your function is marked [@@unboxed] and [@@noalloc] in OCaml then you can avoid
// boxing altogether for f64 arguments using a plain C function and a bytecode function
// definition:
#[no_mangle]
pub extern "C" fn incrf(input: f64) -> f64 {
    input + 1.0
}

#[cfg(feature = "derive")]
#[ocaml::bytecode_func]
pub fn incrf_bytecode(input: f64) -> f64 {
    incrf(input)
}

The OCaml stubs would look like this:

type example = {
    name: string;
    i: int;
}

external incr_example: example -> example = "incr_example"
external build_tuple: int -> int * int * int = "build_tuple"
external average: float array -> float = "average"
external incr: int -> int = "incr"
external incr2: int -> int = "incr2"
external incrf: float -> float = "incrf_bytecode" "incrf" [@@unboxed] [@@noalloc]

Re-exports

pub use ocaml_interop as interop;
pub use ocaml_sys as sys;
pub use crate::custom::Custom;
pub use crate::runtime::*;

Modules

bigarray	bigarray contains wrappers for OCaml Bigarray values. These types can be used to transfer arrays of numbers between Rust and OCaml directly without the allocation overhead of an array or list
custom	Custom types, used for allocating Rust values owned by the OCaml garbage collector
root	Rooted values
runtime	Functions for interacting with the OCaml runtime

Macros

array	Convenience macro to create an OCaml array
body	body! is needed to help the OCaml runtime to manage garbage collection, it should be used to wrap the body of each function exported to OCaml. Panics from Rust code will automatically be unwound/caught here (unless the no-std feature is enabled)
custom	Create a custom OCaml type from an existing Rust type
custom_finalize	Derives Custom with the given finalizer for a type
list	Convenience macro to create an OCaml list

Structs

Array	Array<A> wraps an OCaml 'a array without converting it to Rust
List	List<A> wraps an OCaml 'a list without converting it to Rust, this introduces no additional overhead compared to a Value type
OCaml	Representation of OCaml values.
Pointer	A handle to a Rust value/reference owned by the OCaml heap.
Raw	Wrapper around sys::Value
Runtime	OCaml runtime handle.
Tag	OCaml tags are used to provide type information to the garbage collector

Enums

CamlError	Errors that are translated directly into OCaml exceptions
Error	Error returned by ocaml-rs functions
Value	Value wraps the native OCaml value type

Traits

FromValue	FromValue is used to convert from OCaml values to Rust types
IntoValue	IntoValue is used to convert from Rust types to OCaml values

Type Definitions

Float	OCaml float
Int	Integer type that converts to OCaml int
OCamlRef	An OCamlRef<T> is a reference to a location containing a OCaml<T> value.
Uint	Unsigned integer type that converts to OCaml int

Attribute Macros

bytecode_func	bytecode_func is used export Rust functions to OCaml, performing the necessary wrapping/unwrapping automatically.
func	func is used export Rust functions to OCaml, performing the necessary wrapping/unwrapping automatically.
native_func	native_func is used export Rust functions to OCaml, it has much lower overhead than func and expects all arguments and return type to to be Value.

Derive Macros

FromValue
IntoValue