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]
fn new() -> OwnedEnv
Allocates a new process-independent environment.
fn run<F, R>(&self, closure: F) -> R where
F: for<'a> FnOnce(NifEnv<'a>) -> R,
F: for<'a> FnOnce(NifEnv<'a>) -> R,
Run some code in this environment.
fn send_and_clear<F>(&mut self, recipient: &NifPid, closure: F) where
F: for<'a> FnOnce(NifEnv<'a>) -> NifTerm<'a>,
F: for<'a> FnOnce(NifEnv<'a>) -> NifTerm<'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.)
fn clear(&mut self)
Free all terms in this environment and clear it for reuse.
This invalidates SavedTerm
s 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.
fn save<'a>(&self, term: NifTerm<'a>) -> SavedTerm
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.