Struct abi_stable::sabi_types::LateStaticRef

source ·

#[repr(C)]
pub struct LateStaticRef<T> { /* private fields */ }

Expand description

A late-initialized static reference,with fallible initialization.

As opposed to Once, this allows initialization of its static reference to happen fallibly, by returning a Result<_,_> from the try_init function, or by panicking inside either initialization function.

On Err(_) and panics,one can try initialializing the static reference again.

§Example

This lazily loads a configuration file.


use abi_stable::{
    sabi_types::LateStaticRef,
    std_types::{RBox, RBoxError, RHashMap, RString},
    utils::leak_value,
};

use std::{fs, io, path::Path};

use serde::Deserialize;

#[derive(Deserialize)]
pub struct Config {
    pub user_actions: RHashMap<RString, UserAction>,
}

#[derive(Deserialize)]
pub enum UserAction {
    Include,
    Ignore,
    ReplaceWith,
}

fn load_config(file_path: &Path) -> Result<&'static Config, RBoxError> {
    static CONFIG: LateStaticRef<&Config> = LateStaticRef::new();

    CONFIG.try_init(|| {
        let file = load_file(file_path).map_err(RBoxError::new)?;
        let config =
            serde_json::from_str::<Config>(&file).map_err(RBoxError::new)?;
        Ok(leak_value(config))
    })
}

Implementations§

source §

impl<T> LateStaticRef<T>

source

pub const fn new() -> Self

Constructs the LateStaticRef in an uninitialized state.

§Example

use abi_stable::sabi_types::LateStaticRef;

static LATE_REF: LateStaticRef<&String> = LateStaticRef::new();

source §

impl<T> LateStaticRef<&'static T>

source

pub const fn from_ref(value: &'static T) -> Self

Constructs LateStaticRef, initialized with value.

§Example

use abi_stable::sabi_types::LateStaticRef;

static LATE_REF: LateStaticRef<&&str> = LateStaticRef::from_ref(&"Hello!");

source §

impl<T> LateStaticRef<T>

source

pub const fn from_prefixref(ptr: PrefixRef<T::PrefixFields>) -> Self
where T: PrefixRefTrait + 'static, T::PrefixFields: 'static,

Constructs LateStaticRef from a PrefixRef.

§Example

use abi_stable::{
    pointer_trait::ImmutableRef,
    prefix_type::{PrefixRefTrait, PrefixTypeTrait, WithMetadata},
    sabi_types::LateStaticRef,
    StableAbi,
};

fn main() {
    assert_eq!(LATE_REF.get().unwrap().get_number()(), 100);
}

pub static LATE_REF: LateStaticRef<PersonMod_Ref> = {
    // This is how you can construct a `LateStaticRef<Foo_Ref>`,
    //  from a `Foo_Ref` at compile-time.
    //
    // If you don't need a `LateStaticRef` you can construct a `PersonMod_Ref` constant,
    // and use that.
    LateStaticRef::from_prefixref(MODULE.0)
};

#[repr(C)]
#[derive(StableAbi)]
#[sabi(kind(Prefix))]
pub struct PersonMod {
    /// The `#[sabi(last_prefix_field)]` attribute here means that this is
    /// the last field in this struct that was defined in the
    /// first compatible version of the library.
    /// Moving this attribute is a braeking change.
    #[sabi(last_prefix_field)]
    pub get_number: extern "C" fn() -> u32,
}

const MODULE: PersonMod_Ref = {
    const S: &WithMetadata<PersonMod> =
        &WithMetadata::new(PersonMod { get_number });

    PersonMod_Ref(S.static_as_prefix())
};

extern "C" fn get_number() -> u32 {
    100
}

source §

impl<T> LateStaticRef<T>

source

pub const unsafe fn from_custom(ptr: NonNull<T::PtrTarget>) -> Self
where T: GetPointerKind<Kind = PK_Reference> + 'static, T::PtrTarget: 'static,

Constructs LateStaticRef from a NonNull pointer.

§Safety

The passed in pointer must be valid for passing to <T as ImmutableRef>::from_nonnull, it must be a valid pointer to U, and be valid to dereference for the rest of the program’s lifetime.

§Example

use abi_stable::{
    pointer_trait::{GetPointerKind, PK_Reference},
    sabi_types::LateStaticRef,
    utils::ref_as_nonnull,
    StableAbi,
};

use std::ptr::NonNull;

#[derive(Copy, Clone)]
struct Foo<'a>(&'a u64);

impl<'a> Foo<'a> {
    const fn as_nonnull(self) -> NonNull<u64> {
        ref_as_nonnull(self.0)
    }
}

unsafe impl<'a> GetPointerKind for Foo<'a> {
    type PtrTarget = u64;
    type Kind = PK_Reference;
}

const MODULE: LateStaticRef<Foo<'static>> = {
    unsafe {
        LateStaticRef::from_custom(Foo(&100).as_nonnull())
    }
};

source §

impl<T> LateStaticRef<T>
where T: ImmutableRef + 'static,

source

pub fn try_init<F, E>(&self, initializer: F) -> Result<T, E>
where F: FnOnce() -> Result<T, E>,

Lazily initializes the LateStaticRef with initializer, returning the T if either it was already initialized,or if initalizer returned Ok(..).

If initializer returns an Err(...) this returns the error and allows the LateStaticRef to be initializer later.

If initializer panics,the panic is propagated, and the reference can be initalized later.

§Example

use abi_stable::{sabi_types::LateStaticRef, utils::leak_value};

static LATE: LateStaticRef<&String> = LateStaticRef::new();

static EARLY: LateStaticRef<&&str> = LateStaticRef::from_ref(&"Hello!");

assert_eq!(LATE.try_init(|| Err("oh no!")), Err("oh no!"));
assert_eq!(
    LATE.try_init(|| -> Result<&'static String, ()> {
        Ok(leak_value("Yay".to_string()))
    })
    .map(|s| s.as_str()),
    Ok("Yay"),
);

assert_eq!(EARLY.try_init(|| Err("oh no!")), Ok(&"Hello!"));

source

pub fn init<F>(&self, initializer: F) -> T
where F: FnOnce() -> T,

Lazily initializes the LateStaticRef with initializer, returning the T if either it was already initialized, or initalizer returns it without panicking.

If initializer panics,the panic is propagated, and the reference can be initalized later.

§Example

use abi_stable::{sabi_types::LateStaticRef, utils::leak_value};

static LATE: LateStaticRef<&String> = LateStaticRef::new();

static EARLY: LateStaticRef<&&str> = LateStaticRef::from_ref(&"Hello!");

let _ = std::panic::catch_unwind(|| {
    LATE.init(|| panic!());
});

assert_eq!(LATE.init(|| leak_value("Yay".to_string())), &"Yay");

assert_eq!(EARLY.init(|| panic!()), &"Hello!");

source

pub fn get(&self) -> Option<T>

Returns Some(x:T) if the LateStaticRef was initialized, otherwise returns None.

§Example

use abi_stable::{sabi_types::LateStaticRef, utils::leak_value};

static LATE: LateStaticRef<&String> = LateStaticRef::new();

static EARLY: LateStaticRef<&&str> = LateStaticRef::from_ref(&"Hello!");

let _ = std::panic::catch_unwind(|| {
    LATE.init(|| panic!());
});

assert_eq!(LATE.get(), None);
LATE.init(|| leak_value("Yay".to_string()));
assert_eq!(LATE.get().map(|s| s.as_str()), Some("Yay"));

assert_eq!(EARLY.get(), Some(&"Hello!"));