Struct rustler::env::OwnedEnv [−][src]
pub struct OwnedEnv { /* fields omitted */ }
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
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 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.
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
Auto Trait Implementations
impl RefUnwindSafe for OwnedEnv
impl UnwindSafe for OwnedEnv