Struct abi_stable::sabi_types::StaticRef

source ·

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

Expand description

A wrapper type for vtable static references, and other constants that have non-'static generic parameters but are safe to reference for the lifetime of T.

Purpose

This type is necessary because Rust doesn’t understand that vtables live for 'static, even though they have non-'static type parameters.

Example

This defines a non-extensible vtable,using a StaticRef as the pointer to the vtable.

use abi_stable::{
    marker_type::ErasedObject,
    prefix_type::{PrefixTypeTrait, WithMetadata},
    sabi_extern_fn,
    sabi_types::StaticRef,
    staticref, StableAbi,
};

use std::{marker::PhantomData, ops::Deref};

fn main() {
    let boxed = BoxLike::new("foo".to_string());
    assert_eq!(boxed.as_str(), "foo");
}

/// An ffi-safe `Box<T>`
#[repr(C)]
#[derive(StableAbi)]
pub struct BoxLike<T> {
    data: *mut T,

    vtable: StaticRef<VTable<T>>,

    _marker: PhantomData<T>,
}

impl<T> BoxLike<T> {
    pub fn new(value: T) -> Self {
        Self {
            data: Box::into_raw(Box::new(value)),
            vtable: VTable::<T>::VTABLE,
            _marker: PhantomData,
        }
    }
}

impl<T> Drop for BoxLike<T> {
    fn drop(&mut self) {
        unsafe {
            (self.vtable.drop_)(self.data);
        }
    }
}

impl<T> Deref for BoxLike<T> {
    type Target = T;

    fn deref(&self) -> &T {
        unsafe { &*self.data }
    }
}

#[repr(C)]
#[derive(StableAbi)]
pub struct VTable<T> {
    drop_: unsafe extern "C" fn(*mut T),
}

impl<T> VTable<T> {
    // The `staticref` macro declares a `StaticRef<VTable<T>>` constant.
    staticref!(const VTABLE: Self = Self{
        drop_: drop_box::<T>,
    });
}

#[sabi_extern_fn]
unsafe fn drop_box<T>(object: *mut T) {
    drop(Box::from_raw(object));
}

Implementations

source

impl<T, P> StaticRef<WithMetadata_<T, P>>

source

pub const fn as_prefix(self) -> PrefixRef

Constructs a PrefixRef from self.

This is most useful when you have a generic type that isn’t 'static for type system reasons, but lives for the entire program.

Example

use abi_stable::{
    for_examples::{PhantModule, PhantModule_Ref},
    prefix_type::{PrefixRef, PrefixTypeTrait, WithMetadata},
    std_types::{RNone, RStr},
    staticref,
};

struct Foo<T>(T);

impl<T: Copy> Foo<T> {
    // The `staticref` invocation here declares a
    // `StaticRef<WithMetadata<PhantModule<T>>>` constant.
    staticref!(const WITH_META: WithMetadata<PhantModule<T>> = WithMetadata::new(
        PrefixTypeTrait::METADATA,
        PhantModule {
            first: RNone,
            second: RStr::from_str("hello"),
            third: 100,
            phantom: std::marker::PhantomData,
        },
    ));
}

const MOD: PhantModule_Ref<()> = PhantModule_Ref(Foo::WITH_META.as_prefix());

assert_eq!(MOD.first(), RNone);
assert_eq!(MOD.second().as_str(), "hello");

source

impl<T> StaticRef<T>

source

pub const unsafe fn from_raw(ref_: *const T) -> Self

Constructs this StaticRef from a raw pointer.

Safety

You must ensure that the raw pointer is valid for the entire program’s lifetime.

Example

use abi_stable::sabi_types::StaticRef;

struct GetPtr<T>(T);

impl<T> GetPtr<T> {
    const PTR: *const Option<T> = &None;

    const STATIC: StaticRef<Option<T>> = unsafe { StaticRef::from_raw(Self::PTR) };
}
{}

source

pub const fn new(ref_: &'static T) -> Self

Constructs this StaticRef from a static reference

This implicitly requires that T:'static.

Example

use abi_stable::sabi_types::StaticRef;

struct GetPtr<T>(T);

impl<T> GetPtr<T>
where
    T: 'static,
{
    const REF: &'static Option<T> = &None;

    const STATIC: StaticRef<Option<T>> = StaticRef::new(Self::REF);
}

source

pub fn leak_value(val: T) -> Self

Creates a StaticRef by heap allocating and leaking val.

source

pub fn get<'a>(self) -> &'a T

Gets access to the reference.

This returns &'a T instead of &'static T to support vtables of non-'static types.

Example

use abi_stable::sabi_types::StaticRef;

struct GetPtr<T>(T);

impl<T> GetPtr<T> {
    const PTR: *const Option<T> = &None;

    const STATIC: StaticRef<Option<T>> = unsafe { StaticRef::from_raw(Self::PTR) };
}

let reference: &'static Option<String> = GetPtr::<String>::STATIC.get();

source

pub const fn as_ptr(self) -> *const T

Gets access to the referenced value,as a raw pointer.

Example

use abi_stable::sabi_types::StaticRef;
use std::convert::Infallible;

struct GetPtr<T>(T);

impl<T> GetPtr<T> {
    const PTR: *const Option<T> = &None;

    const STATIC: StaticRef<Option<T>> = unsafe { StaticRef::from_raw(Self::PTR) };
}

let reference: *const Option<Infallible> = GetPtr::<Infallible>::STATIC.as_ptr();

source

pub const unsafe fn transmute(self) -> StaticRef

Transmutes this StaticRef<T> to a StaticRef.

Safety

StaticRef has the same rules that references have regarding transmuting from one type to another:

Example

use abi_stable::sabi_types::StaticRef;

struct GetPtr<T>(T);

impl<T> GetPtr<T> {
    const PTR: *const Option<T> = &None;

    const STATIC: StaticRef<Option<T>> = unsafe { StaticRef::from_raw(Self::PTR) };
}

let reference: StaticRef<Option<[(); 0xFFF_FFFF]>> =
    unsafe { GetPtr::<()>::STATIC.transmute::<Option<[(); 0xFFF_FFFF]>>() };