Struct RRef

pub struct RRef<'a, T> { /* private fields */ }

Equivalent to &'a T, which allows a few more operations without causing Undefined Behavior.

Purpose

This type is used as the &self parameter in abi_stable trait objects because it can be soundly transmuted to point to other smaller but compatible types, then back to the original type.

This crate is tested with miri to detect bugs in unsafe code, which implements the Stacked Borrows model. Because that model forbids &T to &() to &T transmutes (when T isn’t zero-sized), it required defining RRef to allow a reference-like type that can be transmuted.

Example

This example demonstrates how a simple &dyn Any-like type can be implemented.

use abi_stable::{marker_type::ErasedObject, std_types::UTypeId, RRef};

fn main() {
    let value = WithTypeId::new(5u32);
    let erased = value.erase();

    assert_eq!(WithTypeId::downcast::<i32>(erased), None);
    assert_eq!(WithTypeId::downcast::<bool>(erased), None);
    assert_eq!(WithTypeId::downcast::<u32>(erased), Some(&value));
}

// `#[repr(C))]` with a trailing `T` field is required for soundly transmuting from
// `RRef<'a, WithTypeId<T>>` to `RRef<'a, WithTypeId<ErasedObject>>`.
#[repr(C)]
#[derive(Debug, PartialEq)]
struct WithTypeId<T> {
    type_id: UTypeId,
    value: T,
}

impl<T> WithTypeId<T> {
    pub fn new(value: T) -> Self
    where
        T: 'static,
    {
        Self {
            type_id: UTypeId::new::<T>(),
            value,
        }
    }

    pub fn erase(&self) -> RRef<'_, WithTypeId<ErasedObject>> {
        unsafe { RRef::new(self).transmute::<WithTypeId<ErasedObject>>() }
    }
}

impl WithTypeId<ErasedObject> {
    pub fn downcast<T>(this: RRef<'_, Self>) -> Option<&WithTypeId<T>>
    where
        T: 'static,
    {
        if this.get().type_id == UTypeId::new::<T>() {
            // safety: we checked that type parameter was `T`
            unsafe { Some(this.transmute_into_ref::<WithTypeId<T>>()) }
        } else {
            None
        }
    }
}

Type Prefix

A type parameter U is considered a prefix of T in all of these cases:

• U is a zero-sized type with an alignment equal or lower than T

• U is a #[repr(transparent)] wrapper over T

• U and T are both #[repr(C)] structs, in which T starts with the fields of U in the same order, and U has an alignment equal to or lower than T.

Please note that it can be unsound to transmute a non-local type if it has private fields, since it may assume it was constructed in a particular way.

Implementations

impl<'a, T> RRef<'a, T>

pub const fn new(ref_: &'a T) -> RRef<'a, T>

Constructs this RRef from a reference.

Example

use abi_stable::sabi_types::RRef;

struct GetPtr<'a, T>(&'a T);

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

    const STATIC: RRef<'a, Option<T>> = RRef::new(Self::REF);
}

pub const unsafe fn from_raw(ref_: *const T) -> RRef<'a, T>

where T: 'a,

Constructs this RRef from a raw pointer.

Safety

You must ensure that the raw pointer is valid for the 'a lifetime, and points to a fully initialized and aligned T.

Example

use abi_stable::sabi_types::RRef;

struct GetPtr<'a, T>(&'a T);

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

    const STATIC: RRef<'a, Option<T>> = unsafe { RRef::from_raw(Self::PTR) };
}

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

Casts this to an equivalent reference.

Example

use abi_stable::RRef;

let rref = RRef::new(&89);

assert_eq!(rref.get(), &89);

pub const fn get_copy(self) -> T

where T: Copy,

Copies the value that this points to.

Example

use abi_stable::RRef;

let rref = RRef::new(&55);

assert_eq!(rref.get_copy(), 55);

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

Casts this to an equivalent raw pointer.

Example

use abi_stable::RRef;

let rref = RRef::new(&89);

unsafe {
    assert_eq!(*rref.as_ptr(), 89);
}

pub const unsafe fn transmute<U>(self) -> RRef<'a, U>

where U: 'a,

Transmutes this RRef<'a,T> to a RRef<'a,U>.

Safety

Either of these must be the case:

• U is a prefix of T

• RRef<'a, U> was the original type of this RRef<'a, T>.

Example

use abi_stable::RRef;

use std::num::Wrapping;

let rref = RRef::new(&13u32);

// safety: Wrapping is a `#[repr(transparent)]` wrapper with one `pub` field.
let trans = unsafe { rref.transmute::<Wrapping<u32>>() };

assert_eq!(trans, RRef::new(&Wrapping(13u32)));

pub const fn transmute_into_raw<U>(self) -> *const U

Transmutes this to a raw pointer pointing to a different type.

pub const unsafe fn transmute_into_ref<U>(self) -> &'a U

where U: 'a,

Transmutes this to a reference pointing to a different type.

Safety

Either of these must be the case:

• U is a prefix of T

• RRef<'a, U> was the original type of this RRef<'a, T>.

Example

use abi_stable::{std_types::Tuple2, RRef};

unsafe {
    let reff = RRef::new(&Tuple2(3u32, 5u64));
    assert_eq!(reff.transmute_into_ref::<u32>(), &3u32);
}

Trait Implementations

impl<T> AsPtr for RRef<'_, T>

fn as_ptr(&self) -> *const T

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

fn as_rref(&self) -> RRef<'_, T>

Converts this pointer to an RRef.

impl<'a, T, U> CanTransmuteElement<U> for RRef<'a, T>

where U: 'a,

type TransmutedPtr = RRef<'a, U>

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

unsafe fn transmute_element_( self, ) -> <RRef<'a, T> as CanTransmuteElement<U>>::TransmutedPtr

Transmutes the element type of this pointer..

impl<'a, T> Clone for RRef<'a, T>

fn clone(&self) -> RRef<'a, T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a, T> Debug for RRef<'a, T>

where T: Debug,

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

Formats the value using the given formatter.

impl<'a, T> Display for RRef<'a, T>

where T: Display,

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

Formats the value using the given formatter.

impl<'a, T> GetPointerKind for RRef<'a, 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<'a, T> GetStaticEquivalent_ for RRef<'a, T>

where T: StableAbi + 'a,

type StaticEquivalent = _static_RRef<'static, <T as GetStaticEquivalent_>::StaticEquivalent>

The 'static equivalent of Self

impl<'a, T> Hash for RRef<'a, 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<'a, T> Ord for RRef<'a, T>

where T: Ord,

fn cmp(&self, other: &RRef<'a, T>) -> 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<'a, T> PartialEq for RRef<'a, T>

where T: PartialEq,

fn eq(&self, other: &RRef<'a, T>) -> 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<'a, T> PartialOrd for RRef<'a, T>

where T: PartialOrd,

fn partial_cmp(&self, other: &RRef<'a, T>) -> 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<'a, T> StableAbi for RRef<'a, T>

where T: StableAbi + 'a,

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<'a, T> Copy for RRef<'a, T>

impl<'a, T> Eq for RRef<'a, T>

where T: Eq,

impl<'a, T> Send for RRef<'a, T>

where &'a T: Send,

impl<'a, T> Sync for RRef<'a, T>

where &'a T: Sync,