Struct abi_stable::sabi_types::StaticRef

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

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_types::StaticRef,
    utils::transmute_mut_reference,
    StableAbi,
    sabi_extern_fn,
    staticref,
};

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::{Module, Module_Ref},
    prefix_type::{PrefixRef, PrefixTypeTrait, WithMetadata},
    std_types::{RNone, RStr},
    staticref,
};
 
// The `staticref` invocation here declares a `StaticRef<WithMetadata<Module>>` constant.
const WITH_META: &WithMetadata<Module> = &WithMetadata::new(
    PrefixTypeTrait::METADATA,
    Module {
        first: RNone,
        second: RStr::from_str("hello"),
        third: 100,
    },
);
 
const MOD: Module_Ref = Module_Ref(WITH_META.static_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 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 get_raw(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.get_raw();

pub const unsafe fn transmute_ref<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_ref::<Option<[();0xFFF_FFFF]>>()
};

Trait Implementations

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.

impl<T> Clone for StaticRef<T>

pub fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T> Copy for StaticRef<T>

impl<T> Debug for StaticRef<T> where
    T: Debug, 

pub 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.

pub fn deref(&self) -> &T

Dereferences the value.

impl<T> Display for StaticRef<T> where
    T: Display, 

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

Formats the value using the given formatter.

impl<T> Eq for StaticRef<T> where
    T: Eq, 

impl<T> GetPointerKind for StaticRef<T>

type Kind = PK_Reference

The kind of the pointer.

pub const KIND: PointerKind

The kind of the pointer.

impl<T> GetStaticEquivalent_ for StaticRef<T> where
    T: __StableAbi, 

type StaticEquivalent = _static_StaticRef<__GetStaticEquivalent<T>>

impl<T> Hash for StaticRef<T> where
    T: Hash, 

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

Feeds this value into the given Hasher.

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

Feeds a slice of this type into the given Hasher.

impl<T> Ord for StaticRef<T> where
    T: Ord, 

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

This method returns an Ordering between self and other.

#[must_use]pub fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]pub fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]pub fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl<T> PartialEq<StaticRef<T>> for StaticRef<T> where
    T: PartialEq, 

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

This method tests for self and other values to be equal, and is used by ==.

#[must_use]pub fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T> PartialOrd<StaticRef<T>> for StaticRef<T> where
    T: PartialOrd, 

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

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

#[must_use]pub fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use]pub fn le(&self, other: &Rhs) -> bool

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

#[must_use]pub fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]pub fn ge(&self, other: &Rhs) -> bool

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

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

impl<T> StableAbi for StaticRef<T> where
    T: __StableAbi, 

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

Whether this type has a single invalid bit-pattern.

pub const LAYOUT: &'static TypeLayout

The layout of the type provided by implementors.

pub const ABI_CONSTS: AbiConsts

const-equivalents of the associated types.

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