[−][src]Struct rustler::env::OwnedEnv
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.
Methods
impl OwnedEnv
[src]
pub fn new() -> OwnedEnv
[src]
Allocates a new process-independent environment.
pub fn run<F, R>(&self, closure: F) -> R where
F: for<'a> FnOnce(Env<'a>) -> R,
[src]
F: for<'a> FnOnce(Env<'a>) -> R,
Run some code in this environment.
pub fn send_and_clear<F>(&mut self, recipient: &LocalPid, closure: F) where
F: for<'a> FnOnce(Env<'a>) -> Term<'a>,
[src]
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.)
pub fn clear(&mut self)
[src]
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.
pub fn save<'a>(&self, term: Term<'a>) -> SavedTerm
[src]
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 !Sync for OwnedEnv
impl Unpin for OwnedEnv
impl UnwindSafe for OwnedEnv
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,