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();
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
impl OwnedEnv
sourcepub fn run<F, R>(&self, closure: F) -> Rwhere
F: for<'a> FnOnce(Env<'a>) -> R,
pub fn run<F, R>(&self, closure: F) -> Rwhere
F: for<'a> FnOnce(Env<'a>) -> R,
Run some code in this environment.
sourcepub fn send_and_clear<F>(&mut self, recipient: &LocalPid, closure: F)where
F: for<'a> FnOnce(Env<'a>) -> Term<'a>,
pub fn send_and_clear<F>(&mut self, recipient: &LocalPid, 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.)
sourcepub fn clear(&mut self)
pub 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.
sourcepub fn save(&self, term: Term<'_>) -> SavedTerm
pub fn save(&self, term: Term<'_>) -> 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.