Struct rustler::env::Env

pub struct Env<'a> { /* private fields */ }

On each NIF call, a Env is passed in. The Env is used for most operations that involve communicating with the BEAM, like decoding and encoding terms.

There is no way to allocate a Env at the moment, but this may be possible in the future.

Implementations

impl<'a> Env<'a>

pub fn pid(self) -> LocalPid

Return the calling process’s pid.

Panics

Panics if this environment is process-independent. (The only way to get such an environment is to use OwnedEnv. The Env that Rustler passes to NIFs when they’re called is always associated with the calling Erlang process.)

pub fn is_process_alive(self, pid: LocalPid) -> bool

Checks whether the given process is alive

impl<'a> Env<'a>

pub unsafe fn new<T>(_lifetime_marker: &'a T, env: NIF_ENV) -> Env<'a>

Create a new Env. For the _lifetime_marker argument, pass a reference to any local variable that has its own lifetime, different from all other Env values. The purpose of the argument is to make it easier to know for sure that the Env you’re creating has a unique lifetime (i.e. that you’re following the most important safety rule of Rustler).

Unsafe

Don’t create multiple Envs with the same lifetime.

pub fn as_c_arg(self) -> NIF_ENV

pub fn error_tuple(self, reason: impl Encoder) -> Term<'a>

Convenience method for building a tuple {error, Reason}.

pub fn send( self, pid: &LocalPid, message: impl Encoder ) -> Result<(), SendError>

Send a message to a process.

The Erlang VM imposes some odd restrictions on sending messages. You can send messages in either of these situations:

• The current thread is managed by the Erlang VM, and self is the environment of the calling process (that is, the environment that Rustler passed in to your NIF); or

• The current thread is not managed by the Erlang VM.

The result indicates whether the send was successful, see also enif_send.

Panics

Panics if the above rules are broken (by trying to send a message from an OwnedEnv on a thread that’s managed by the Erlang VM).

pub fn whereis_pid(self, name_or_pid: impl Encoder) -> Option<LocalPid>

Attempts to find the PID of a process registered by name_or_pid

Safe wrapper around enif_whereis_pid.

Returns

• Some(pid) if name_or_pid is already a PID.
• Some(pid) if name_or_pid is an atom and an alive process is currently registered under the given name.
• None if name_or_pid is an atom but there is no alive process registered under this name.
• None if name_or_pid is not a PID or atom.

pub fn binary_to_term(self, data: &[u8]) -> Option<(Term<'a>, usize)>

Decodes binary data to a term.

Follows the erlang External Term Format.

pub unsafe fn binary_to_term_trusted( self, data: &[u8] ) -> Option<(Term<'a>, usize)>

Like binary_to_term, but can only be called on valid and trusted data.

Trait Implementations

impl<'a> Clone for Env<'a>

fn clone(&self) -> Env<'a>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a, 'b> PartialEq<Env<'b>> for Env<'a>

Two environments are equal if they’re the same NIF_ENV value.

A Env<'a> is equal to a Env<'b> if and only if 'a and 'b are the same lifetime.

fn eq(&self, other: &Env<'b>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a> Copy for Env<'a>