Rustler
Documentation | Getting Started | 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.
Features
- Safety
- The code you write in a Rust NIF should never be able to crash the BEAM.
- Interop
- Decoding and encoding rust values into Erlang terms is as easy as a function
- call.
- Type composition
- Making a Rust struct encodable and decodable to Erlang or Elixir can be done
- with a single attribute.
- Resource objects
- Enables you to safely pass a reference to a Rust struct into Erlang code. The
- struct will be automatically dropped when it’s no longer referenced.
Getting started
The easiest way of getting started is the rustler Elixir library.
- Add the rustler Elixir library as a dependency of your project.
- Run
mix rustler.new
to generate a new NIF in your project. Follow the instructions. - If you are already using
serde
and/or have been usingserde_rustler
before, please enable theserde
feature in your NIF crate’sCargo.toml
on therustler
dependency.
What it looks like
This is the code for a minimal NIF that adds two numbers and returns the result.
#[rustler::nif]
fn add(a: i64, b: i64) -> i64 {
a + b
}
rustler::init!("Elixir.Math");
Community
You can find us in the #rustler:matrix.org
channel on Matrix
or in the #rustler
channel in the Elixir lang Slack.