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
impl OwnedEnv
sourcepub fn send_and_clear<'a, F, T>(
&mut self,
recipient: &LocalPid,
closure: F
) -> Result<(), SendError>
pub fn send_and_clear<'a, F, T>( &mut self, recipient: &LocalPid, closure: F ) -> Result<(), SendError>
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.)
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: impl Encoder) -> SavedTerm
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 ...
});
});
}
Note: There is no way to save terms across OwnedEnv::send()
or clear()
.
If you try, the .load()
call will panic.