Struct StaticRef

pub struct StaticRef<T> { /* private fields */ }

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

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

pub const fn as_prefix(self) -> PrefixRef<P>

Constructs a PrefixRef<P> 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(
        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");

impl<T> StaticRef<T>

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) };
}
{}

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);
}

pub fn leak_value(val: T) -> Self

Creates a StaticRef by heap allocating and leaking val.

pub const 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();

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();

pub const unsafe fn transmute<U>(self) -> StaticRef<U>

Transmutes this StaticRef<T> to a StaticRef<U>.

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]>>() };

Trait Implementations

impl<T> AsPtr for StaticRef<T>

fn as_ptr(&self) -> *const T

Gets a const raw pointer to the value that this points to.

fn as_rref(&self) -> RRef<'_, Self::PtrTarget>

Converts this pointer to an RRef.

impl<T, U> CanTransmuteElement<U> for StaticRef<T>

type TransmutedPtr = StaticRef<U>

The type of the pointer after it’s element type has been changed.

unsafe fn transmute_element_(self) -> StaticRef<U>

Transmutes the element type of this pointer..

impl<T> Clone for StaticRef<T>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T> Debug for StaticRef<T>

where T: Debug,

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

Formats the value using the given formatter.

impl<T> Deref for StaticRef<T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<T> Display for StaticRef<T>

where T: Display,

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

Formats the value using the given formatter.

impl<T> GetPointerKind for StaticRef<T>

type Kind = PK_Reference

The kind of the pointer.

type PtrTarget = T

What this pointer points to.

const KIND: PointerKind = <Self::Kind as PointerKindVariant>::VALUE

The value-level version of the Kind associated type.

impl<T> GetStaticEquivalent_ for StaticRef<T>

where T: __StableAbi,

type StaticEquivalent = _static_StaticRef<<T as GetStaticEquivalent_>::StaticEquivalent>

The 'static equivalent of Self

impl<T> Hash for StaticRef<T>

where T: Hash,

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T> Ord for StaticRef<T>

where T: Ord,

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<T> PartialEq for StaticRef<T>

where T: PartialEq,

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl<T> PartialOrd for StaticRef<T>

where T: PartialOrd,

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T> StableAbi for StaticRef<T>

where T: __StableAbi,

const LAYOUT: &'static TypeLayout

The layout of the type provided by implementors.

type IsNonZeroType = <NonNull<T> as StableAbi>::IsNonZeroType

Whether this type has a single invalid bit-pattern.

const ABI_CONSTS: AbiConsts = _

const-equivalents of the associated types.

impl<T> Copy for StaticRef<T>

impl<T> Eq for StaticRef<T>

where T: Eq,

impl<'a, T: 'a> Send for StaticRef<T>

where &'a T: Send,

impl<'a, T: 'a> Sync for StaticRef<T>

where &'a T: Sync,