Struct rustler::env::OwnedEnv [] [src]

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::NifPid;
use rustler::NifEncoder;

fn send_string_to_pid(data: &str, pid: &NifPid) {
    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
[src]

Allocates a new process-independent environment.

Run some code in this environment.

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.)

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.

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

For your safety, Rust doesn't let you save NifTerm 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: NifEnv<'a>, term: NifTerm<'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 Send for OwnedEnv
[src]

impl Drop for OwnedEnv
[src]

A method called when the value goes out of scope. Read more