Crate rustler

Github Example

Rustler is a library for writing Erlang NIFs in safe Rust code. That means there should be no ways to crash the BEAM (Erlang VM). The library provides facilities for generating the boilerplate for interacting with the BEAM, handles encoding and decoding of Erlang terms, and catches rust panics before they unwind into C.

The library provides functionality for both Erlang and Elixir, however Elixir is favored as of now.

This crate provides the entire runtime library for rustler. Code generators are located in the rustler_codegen library.

Getting Started

There is a :rustler package on hex.pm that provides functionality which makes working with Rustler easier, including project generators, an automatic NIF compiler for Mix, and utilities for loading the compiled NIF.

For more information about this, see the documentation for rustler.

Re-exports

pub use crate::types::Atom;

pub use crate::types::Binary;

pub use crate::types::Decoder;

pub use crate::types::Encoder;

pub use crate::types::ErlOption;

pub use crate::types::ListIterator;

pub use crate::types::LocalPid;

pub use crate::types::MapIterator;

pub use crate::types::NewBinary;

pub use crate::types::OwnedBinary;

pub use crate::types::Reference;

pub use crate::schedule::SchedulerFlags;

pub use crate::env::Env;

pub use crate::env::OwnedEnv;

pub use crate::thread::spawn;

pub use crate::thread::JobSpawner;

pub use crate::thread::ThreadSpawner;

pub use crate::error::Error;

pub use crate::return::Return;

pub use crate::serde::SerdeTerm;

Modules

env

error

return

schedule

serde

(Experimental) Serde Support

sys

Low level Rust bindings to the Erlang NIF API.

thread

types

Macros

atoms

Macro for defining Rust functions that return Erlang atoms.

enif_fprintf

enif_make_list

enif_make_tuple

enif_snprintf

init

Initialise the Native Implemented Function (NIF) environment and register NIF functions in an Elixir module.

resource

Deprecated resource registration method

Structs

BigInt

A big signed integer type.

Monitor

Handle for a monitor created using ResourceArc<T>::monitor.

Nif

ResourceArc

A reference to a resource of type T.

ResourceInitError

Indicates that a resource has not been registered successfully

Term

Term is used to represent all erlang terms. Terms are always lifetime limited by a Env.

Enums

TermType

Traits

Resource

Trait that needs to be implemented to use a type as a NIF resource type.

Type Aliases

NifResult

Attribute Macros

nif

Wrap a function in a Native Implemented Function (NIF) implementation, so that it can be called from Elixir, with all encoding and decoding steps done automatically.

resource_impl

Helper attribute for Resource implementations

Derive Macros

NifException

Derives implementations for the Encoder and Decoder traits which convert between an Elixir exception and a Rust struct.

NifMap

Derives implementations for the Encoder and Decoder traits which convert between Rust struct and an Elixir map.

NifRecord

Derives implementations for the Encoder and Decoder traits which convert between a Rust struct and an Elixir record.

NifStruct

Derives implementations for the Encoder and Decoder traits which convert between an Elixir struct and a Rust struct.

NifTaggedEnum

Implementation of the NifTaggedEnum macro that lets the user annotate an enum that will generate elixir values when encoded. This can be used for any rust enums and will generate three types of values based on the kind of the enum. For example from the test code:

NifTuple

Derives implementations for the Encoder and Decoder traits which convert between a Rust struct and an Elixir tuple.

NifUnitEnum

Derives implementations for the Encoder and Decoder traits which convert between an enum and a union of elixir atoms.

NifUntaggedEnum

Derives implementations for the Encoder and Decoder traits which convert between a Rust enum and a union of Elixir types.