Trait FromStatic 

pub trait FromStatic {
    // Required methods
    fn name() -> Cow<'static, str>;
    fn instance_ptr() -> InstanceResult<*mut Self>;

    // Provided methods
    unsafe fn instance_mut() -> InstanceResult<&'static mut Self> { ... }
    unsafe fn instance() -> InstanceResult<&'static Self> { ... }
}

A trait for all objects that are instantiated a single time at a fixed point in memory.

This is automatically implemented for FromSingletons generated using the singleton attribute macro, and may be manually implemented for other types that have different ways of looking up their locations in-memory.

Required Methods

fn name() -> Cow<'static, str>

The name of this object. Used for debugging purposes.

fn instance_ptr() -> InstanceResult<*mut Self>

Looks up the single global instance of this object as a reference.

This function is safe because it’s always already unsafe to dereference a pointer. Most callers should use FromStatic::instance or FromStatic::instance_mut instead, which have more explicit safety requirements but provide access to Rust references in exchange.

Provided Methods

unsafe fn instance_mut() -> InstanceResult<&'static mut Self>

Looks up the single global instance of this object as a mutable reference.

Safety

The caller must ensure that access to the static object is exclusive, both with Rust and the game’s code. This means that this should only ever be called from the game’s main thread (typically either from the task system or from hooked functions that run in the main thread).

Individual implementations may add additional safety requirements.

unsafe fn instance() -> InstanceResult<&'static Self>

Looks up the single global instance of this object as a reference.

Safety

The caller must ensure that no mutable references exist to the static object and that no fields outside of UnsafeCells are mutated by the game while this reference exists. This is generally safe to use on the main thread. It’s safe to use on other threads as long as the object is thread-safe, which should be noted in its documentation.

Individual implementations may add additional safety requirements.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl<T: FromSingleton> FromStatic for T

Looks up instances of singleton instances by their name. Some singletons aren’t necessarily always instanciated and available. Discovered singletons are cached so invokes after the first will be much faster.

Note: currently this never returns InstanceError::NotFound, but callers shouldn’t rely on that being true into the future.