Struct emacs::GlobalRef

#[repr(transparent)]pub struct GlobalRef { /* fields omitted */ }

A "global reference" that can live outside the scope of an Env. This is useful for sharing an otherwise short-lived Lisp Value across multiple invocations of Rust functions defined with defun. Examples include efficient access to interned symbols or Lisp functions, and Rust-based multi-threading.

Implementation

Cloning this struct requires an Env, so it doesn't implement Clone.

free_global_ref requires an Env. Therefore, to avoid leaking the underlying Value, free should be used to free a global reference, instead of drop. For the use case of accessing interned symbols and Lisp functions, this is a non-issue, as the values are supposed to be "static" anyway.

The above is a shortcoming in the design of emacs-module. There are 2 possible ways to fix it:

• Make free_global_ref work without an env, like Erlang's enif_release_resource.
• Allow user_ptr's finalizer to access the env, to properly free associated global refs.

Methods

impl GlobalRef

pub fn call<'e, A>(&'e self, env: &'e Env, args: A) -> Result<Value> where
    A: IntoLispArgs<'e>, 

Calls this reference's value with the given arguments. An error is signaled if it is actually not a Lisp's callable.

args should be an array/slice of Value, or a tuple of different types, each implementing IntoLisp.

pub unsafe fn call_unprotected<'e, A>(
    &'e self,
    env: &'e Env,
    args: A
) -> Result<Value> where
    A: IntoLispArgs<'e>, 

Like call, except that the returned Value is not protected against Emacs GC's bug #31238, which caused issue #2.

Safety

This can be used as an optimization, in situations when the returned Value is unused, or when its usage is shorter than the lifespan of the underlying Lisp object.

impl GlobalRef

pub fn new(value: Value) -> Self

Creates a new global reference for the given Value.

pub fn free(self, env: &Env) -> Result<()>

Frees this global reference.

pub fn bind<'e, 'g: 'e>(&'g self, env: &'e Env) -> Value<'e>

Returns the underlying Value, scoping its lifetime to the given Env.

pub fn clone(&self, env: &Env) -> Self

Returns a copy of this global reference.

Trait Implementations

impl Debug for GlobalRef

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<'e> FromLisp<'e> for GlobalRef

fn from_lisp(value: Value<'e>) -> Result<Self>

impl<'e> IntoLisp<'e> for &'e GlobalRef

fn into_lisp(self, env: &'e Env) -> Result<Value<'e>>

impl Send for GlobalRef

impl Sync for GlobalRef