Skip to content
Safe Rust bridge for creating Erlang NIF functions
Branch: master
Clone or download
Latest commit 64b49f7 Mar 9, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.cargo
rustler add base for scheduling Mar 9, 2019
rustler_codegen (release) 0.20.0 Feb 26, 2019
rustler_mix Generate .cargo/config (#192) Mar 6, 2019
rustler_tests implement trait-based returns Mar 9, 2019
.gitignore Fix for Github issue #152 (#153) Jun 15, 2018
.travis.yml Source cargo environment (#176) Jan 5, 2019
Cargo.lock.old add base for scheduling Mar 9, 2019
Cargo.toml Generate .cargo/config (#192) Mar 6, 2019
LICENSE-APACHE change license to MIT/APACHE dual license Apr 8, 2016
LICENSE-MIT change project name in LICENSE-MIT Apr 8, 2016
README.md
RELEASE_CHECKLIST.md add basic test suite, number tests, list tests May 10, 2016
release.sh

README.md

Rustler

Documentation | Getting Started | Example

Build Status

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.

NOTE: If you have previously used Rustler, you need to run mix archive.uninstall rustler_installer.ez to remove it before generating the NIF.

How it looks like

This is the code for a minimal NIF that adds two numbers and returns the result.

#[macro_use] extern crate rustler;
#[macro_use] extern crate lazy_static;

use rustler::{Env, Term, NifResult, Encoder};

mod atoms {
    rustler_atoms! {
        atom ok;
    }
}

rustler_export_nifs!(
    "Elixir.TestNifModule",
    [("add", 2, add)],
    None
);

fn add<'a>(env: Env<'a>, args: &[Term<'a>]) -> NifResult<Term<'a>> {
    let num1: i64 = args[0].decode()?;
    let num2: i64 = args[1].decode()?;

    Ok((atoms::ok(), num1 + num2).encode(env))
}

Supported nif_version

Rustler uses erlang:system_info(nif_version) to detect the supported NIF version of the Erlang/OTP system for which the NIF is to be compiled. It is possible to restrict the NIF version to an older version if the NIF is to be compiled for an older version of Erlang. For example, if the target NIF version should be 2.7 (Erlang/OTP 17.3), this can be defined using an environment variable:

RUSTLER_NIF_VERSION=2.7 mix compile

Community

You can find us in #rustler on freenode or the elixir-lang slack.

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

You can’t perform that action at this time.