Struct rustler::env::OwnedEnv

source ·

pub struct OwnedEnv { /* private fields */ }

Expand description

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::LocalPid;
use rustler::Encoder;

fn send_string_to_pid(data: &str, pid: &LocalPid) {
    let mut msg_env = OwnedEnv::new();
    let _ = 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.

Implementations§

source §

impl OwnedEnv

source

pub fn new() -> OwnedEnv

Allocates a new process-independent environment.

source

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

Run some code in this environment.

source

pub fn send_and_clear<'a, F, T>( &mut self, recipient: &LocalPid, closure: F ) -> Result<(), SendError>
where F: FnOnce(Env<'a>) -> T, T: Encoder,

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.

The result is the same as what Env::send would return.

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

source

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.

source

pub fn save(&self, term: impl Encoder) -> 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 ...
        });
    });
}