Struct rustler::env::OwnedEnv

pub struct OwnedEnv { /* fields omitted */ }

A process-independent environment, a place where Erlang terms can be created outside of a NIF call.

Rust code can use an owned environment to build a message and send it to an Erlang process.

use rustler::env::OwnedEnv;
use rustler::types::pid::Pid;
use rustler::Encoder;

fn send_string_to_pid(data: &str, pid: &Pid) {
    let mut msg_env = OwnedEnv::new();
    msg_env.send_and_clear(pid, |env| data.encode(env));
}

There's no way to run Erlang code in an OwnedEnv. It's not a process. It's just a workspace for building terms.

Methods

impl OwnedEnv

pub fn new() -> OwnedEnv

Allocates a new process-independent environment.

pub fn run<F, R>(&self, closure: F) -> R where
    F: for<'a> FnOnce(Env<'a>) -> R, 

Run some code in this environment.

pub fn send_and_clear<F>(&mut self, recipient: &Pid, closure: F) where
    F: for<'a> FnOnce(Env<'a>) -> Term<'a>, 

Send a message from a Rust thread to an Erlang process.

The environment is cleared as though by calling the .clear() method. To avoid that, use env.send(pid, term) instead.

Panics

Panics if called from a thread that is managed by the Erlang VM. You can only use this method on a thread that was created by other means. (This curious restriction is imposed by the Erlang VM.)

pub fn clear(&mut self)

Free all terms in this environment and clear it for reuse.

This invalidates SavedTerms that were saved in this environment; if you later try to .load() one, you'll get a panic.

Unless you call this method after a call to run(), all terms created within the environment hang around in memory until the OwnedEnv is dropped: garbage collection does not continually happen as needed in a NIF environment.

pub fn save<'a>(&self, term: Term<'a>) -> SavedTerm

Save a term for use in a later call to .run() or .send().

For your safety, Rust doesn't let you save Term values from one .run() call to a later .run() call. If you try, it'll complain about lifetimes.

.save() offers a way to do this. For example, maybe you'd like to copy a term from the caller into an OwnedEnv, then use that term on another thread.

use rustler::env::OwnedEnv;
use std::thread;

fn thread_example<'a>(env: Env<'a>, term: Term<'a>) {
    // Copy `term` into a new OwnedEnv, for use on another thread.
    let mut thread_env = OwnedEnv::new();
    let saved_term = thread_env.save(term);

    thread::spawn(move || {
        // Now run some code on the thread, using the saved term.
        thread_env.run(|env| {
            let term = saved_term.load(env);
            //... do stuff with term ...
        });
    });
}

Note: There is no way to save terms across OwnedEnv::send() or clear(). If you try, the .load() call will panic.

Trait Implementations

impl Drop for OwnedEnv

fn drop(&mut self)

Executes the destructor for this type.

impl Send for OwnedEnv