Struct abi_stable::sabi_trait::RObject

#[repr(C)]
pub struct RObject<'lt, P, I, V>
where
    P: GetPointerKind,
{ /* private fields */ }

RObject implements ffi-safe trait objects, for a minimal selection of traits.

The main use of RObject<_> is as the default backend for #[sabi_trait] generated trait objects.

Construction

RObject<_> is how #[sabi_trait]-based ffi-safe trait objects are implemented, and there’s no way to construct it separate from those.

Trait object

RObject<'borrow, Pointer<()>, Interface, VTable> can be used as a trait object for any combination of the traits listed below:

• Send

• Sync

• Unpin

• Debug

• Display

• Error

• Clone

Deconstruction

RObject<_> can be unwrapped into a concrete type, within the same dynamic library/executable that constructed it, using these (fallible) conversion methods:

• downcast_into: Unwraps into a pointer to T.Requires T: 'static.

• downcast_as: Unwraps into a &T.Requires T: 'static.

• downcast_as_mut: Unwraps into a &mut T.Requires T: 'static.

RObject can only be converted back if the trait object was constructed to allow it.

Implementations

impl<'lt, P, I, V> RObject<'lt, P, I, V>

where P: AsPtr<PtrTarget = ()>,

pub unsafe fn with_vtable<OrigPtr>( ptr: OrigPtr, vtable: PrefixRef<V>, ) -> RObject<'lt, P, I, V>

where OrigPtr: CanTransmuteElement<(), TransmutedPtr = P>, OrigPtr::PtrTarget: Sized + 'lt, P: AsPtr<PtrTarget = ()>,

Constructs an RObject from a pointer and an extra vtable.

This is mostly intended to be called by #[sabi_trait] generated trait objects.

Safety

These are the requirements for the caller:

• P must be a pointer to the type that the vtable functions take as the first parameter.

• The vtable must not come from a reborrowed RObject (created using RObject::reborrow or RObject::reborrow_mut).

• The vtable must be the SomeVTableName of a struct declared with #[derive(StableAbi)] #[sabi(kind(Prefix(prefix_ref= SomeVTableName)))].

• The vtable must have RObjectVtable_Ref as its first declared field

impl<'borr, 'a, I, V> RObject<'borr, RRef<'a, ()>, I, V>

pub const unsafe fn with_vtable_const<T, Downcasting>( ptr: &'a T, vtable: PrefixRef<V>, ) -> Self

where T: 'borr,

This function allows constructing an RObject in a constant/static.

This is mostly intended for #[sabi_trait]-generated trait objects

Safety

This has the same safety requirements as RObject::with_vtable

Example

Because this is intended for #[sabi_trait] generated trait objects, this demonstrates how to construct one in a constant.

use abi_stable::sabi_trait::{
    doc_examples::ConstExample_CTO,
    prelude::TD_Opaque,
};

const EXAMPLE0: ConstExample_CTO<'static, 'static> =
    ConstExample_CTO::from_const(&0usize, TD_Opaque);

impl<'lt, P, I, V> RObject<'lt, P, I, V>

where P: GetPointerKind,

pub fn downcast_into<T>(self) -> Result<P::TransmutedPtr, UneraseError<Self>>

where T: 'static, P: AsPtr<PtrTarget = ()> + CanTransmuteElement<T>,

Attempts to unerase this trait object into the pointer it was constructed with.

Errors

This will return an error in any of these conditions:

• It is called in a dynamic library/binary outside the one from which this RObject was constructed.

• The trait object wrapping this RObject was constructed with a TD_CanDowncast argument.

• T is not the concrete type this RObject<_> was constructed with.

Example

use abi_stable::{
    sabi_trait::doc_examples::Doer_TO, std_types::RBox,
    type_level::downcasting::TD_CanDowncast,
};

let to = || Doer_TO::from_value(5usize, TD_CanDowncast);

// `to.obj` is an RObject
assert_eq!(
    to().obj.downcast_into::<usize>().ok(),
    Some(RBox::new(5usize))
);
assert_eq!(to().obj.downcast_into::<u8>().ok(), None);

pub fn downcast_as<T>(&self) -> Result<&T, UneraseError<&Self>>

where T: 'static, P: AsPtr<PtrTarget = ()> + CanTransmuteElement<T>,

Attempts to unerase this trait object into a reference of the value was constructed with.

Errors

This will return an error in any of these conditions:

• It is called in a dynamic library/binary outside the one from which this RObject was constructed.

• The trait object wrapping this RObject was constructed with a TD_CanDowncast argument.

• T is not the concrete type this RObject<_> was constructed with.

Example

use abi_stable::{
    sabi_trait::doc_examples::Doer_TO, std_types::RArc,
    type_level::downcasting::TD_CanDowncast, RMut, RRef,
};

{
    let to: Doer_TO<'_, RArc<()>> =
        Doer_TO::from_ptr(RArc::new(8usize), TD_CanDowncast);

    // `to.obj` is an RObject
    assert_eq!(to.obj.downcast_as::<usize>().ok(), Some(&8usize));
    assert_eq!(to.obj.downcast_as::<u8>().ok(), None);
}
{
    // `#[sabi_trait]` trait objects constructed from `&`
    // use `RRef<'_, ()>` instead of `&'_ ()`
    // since `&T` can't soundly be transmuted back and forth into `&()`
    let to: Doer_TO<'_, RRef<'_, ()>> = Doer_TO::from_ptr(&13usize, TD_CanDowncast);

    assert_eq!(to.obj.downcast_as::<usize>().ok(), Some(&13usize));
    assert_eq!(to.obj.downcast_as::<u8>().ok(), None);
}
{
    let mmut = &mut 21usize;
    // `#[sabi_trait]` trait objects constructed from `&mut`
    // use `RMut<'_, ()>` instead of `&'_ mut ()`
    // since `&mut T` can't soundly be transmuted back and forth into `&mut ()`
    let to: Doer_TO<'_, RMut<'_, ()>> = Doer_TO::from_ptr(mmut, TD_CanDowncast);

    assert_eq!(to.obj.downcast_as::<usize>().ok(), Some(&21usize));
    assert_eq!(to.obj.downcast_as::<u8>().ok(), None);
}

pub fn downcast_as_mut<T>(&mut self) -> Result<&mut T, UneraseError<&mut Self>>

where T: 'static, P: AsMutPtr<PtrTarget = ()> + CanTransmuteElement<T>,

Attempts to unerase this trait object into a mutable reference of the value was constructed with.

Errors

This will return an error in any of these conditions:

• It is called in a dynamic library/binary outside the one from which this RObject was constructed.

• The trait object wrapping this RObject was constructed with a TD_CanDowncast argument.

• T is not the concrete type this RObject<_> was constructed with.

Example

use abi_stable::{
    sabi_trait::doc_examples::Doer_TO, std_types::RBox,
    type_level::downcasting::TD_CanDowncast, RMut, RRef,
};

{
    let mut to: Doer_TO<'_, RBox<()>> =
        Doer_TO::from_value(34usize, TD_CanDowncast);

    // `to.obj` is an RObject
    assert_eq!(to.obj.downcast_as_mut::<usize>().ok(), Some(&mut 34usize));
    assert_eq!(to.obj.downcast_as_mut::<u8>().ok(), None);
}
{
    let mmut = &mut 55usize;
    // `#[sabi_trait]` trait objects constructed from `&mut`
    // use `RMut<'_, ()>` instead of `&'_ mut ()`
    // since `&mut T` can't soundly be transmuted back and forth into `&mut ()`
    let mut to: Doer_TO<'_, RMut<'_, ()>> = Doer_TO::from_ptr(mmut, TD_CanDowncast);

    assert_eq!(to.obj.downcast_as_mut::<usize>().ok(), Some(&mut 55usize));
    assert_eq!(to.obj.downcast_as_mut::<u8>().ok(), None);
}

pub unsafe fn unchecked_downcast_into<T>(self) -> P::TransmutedPtr

where P: AsPtr<PtrTarget = ()> + CanTransmuteElement<T>,

Unwraps the RObject<_> into a pointer to T, without checking whether T is the type that the RObject was constructed with.

Safety

You must check that T is the type that RObject was constructed with through other means.

Example

use abi_stable::{
    sabi_trait::doc_examples::Doer_TO, std_types::RBox,
    type_level::downcasting::TD_Opaque,
};

let to = || Doer_TO::from_value(5usize, TD_Opaque);

unsafe {
    // `to.obj` is an RObject
    assert_eq!(
        to().obj.unchecked_downcast_into::<usize>(),
        RBox::new(5usize)
    );
}

pub unsafe fn unchecked_downcast_as<T>(&self) -> &T

where P: AsPtr<PtrTarget = ()>,

Unwraps the RObject<_> into a reference to T, without checking whether T is the type that the RObject was constructed with.

Safety

You must check that T is the type that RObject was constructed with through other means.

Example

use abi_stable::{
    sabi_trait::doc_examples::Doer_TO, std_types::RArc,
    type_level::downcasting::TD_Opaque, RMut, RRef,
};

{
    let to: Doer_TO<'_, RArc<()>> = Doer_TO::from_ptr(RArc::new(8usize), TD_Opaque);

    unsafe {
        // `to.obj` is an RObject
        assert_eq!(to.obj.unchecked_downcast_as::<usize>(), &8usize);
    }
}
{
    // `#[sabi_trait]` trait objects constructed from `&`
    // use `RRef<'_, ()>` instead of `&'_ ()`
    // since `&T` can't soundly be transmuted back and forth into `&()`
    let to: Doer_TO<'_, RRef<'_, ()>> = Doer_TO::from_ptr(&13usize, TD_Opaque);

    unsafe {
        assert_eq!(to.obj.unchecked_downcast_as::<usize>(), &13usize);
    }
}
{
    let mmut = &mut 21usize;
    // `#[sabi_trait]` trait objects constructed from `&mut`
    // use `RMut<'_, ()>` instead of `&'_ mut ()`
    // since `&mut T` can't soundly be transmuted back and forth into `&mut ()`
    let to: Doer_TO<'_, RMut<'_, ()>> = Doer_TO::from_ptr(mmut, TD_Opaque);

    unsafe {
        assert_eq!(to.obj.unchecked_downcast_as::<usize>(), &21usize);
    }
}

pub unsafe fn unchecked_downcast_as_mut<T>(&mut self) -> &mut T

where P: AsMutPtr<PtrTarget = ()>,

Unwraps the RObject<_> into a mutable reference to T, without checking whether T is the type that the RObject was constructed with.

Safety

You must check that T is the type that RObject was constructed with through other means.

Example

use abi_stable::{
    sabi_trait::doc_examples::Doer_TO, std_types::RBox,
    type_level::downcasting::TD_Opaque, RMut, RRef,
};

{
    let mut to: Doer_TO<'_, RBox<()>> = Doer_TO::from_value(34usize, TD_Opaque);

    unsafe {
        // `to.obj` is an RObject
        assert_eq!(to.obj.unchecked_downcast_as_mut::<usize>(), &mut 34usize);
    }
}
{
    let mmut = &mut 55usize;
    // `#[sabi_trait]` trait objects constructed from `&mut`
    // use `RMut<'_, ()>` instead of `&'_ mut ()`
    // since `&mut T` can't soundly be transmuted back and forth into `&mut ()`
    let mut to: Doer_TO<'_, RMut<'_, ()>> = Doer_TO::from_ptr(mmut, TD_Opaque);

    unsafe {
        assert_eq!(to.obj.unchecked_downcast_as_mut::<usize>(), &mut 55usize);
    }
}

impl<'lt, P, I, V> RObject<'lt, P, I, V>

where P: GetPointerKind, I: InterfaceType,

pub fn reborrow<'re>(&'re self) -> RObject<'lt, RRef<'re, ()>, I, V>

where P: AsPtr<PtrTarget = ()>, PrivStruct: ReborrowBounds<I::Send, I::Sync>,

Creates a shared reborrow of this RObject.

This is only callable if RObject is either Send + Sync or !Send + !Sync.

Example

use abi_stable::{
    sabi_trait::doc_examples::Doer_TO, std_types::RBox,
    type_level::downcasting::TD_Opaque, RMut, RRef,
};

let mut to: Doer_TO<'_, RBox<()>> = Doer_TO::from_value(13usize, TD_Opaque);

// `to.obj` is an RObject
assert_eq!(debug_string(to.obj.reborrow()), "13");
assert_eq!(debug_string(to.obj.reborrow()), "13");

// `#[sabi_trait]` trait objects have an equivalent `sabi_reborrow` method.
assert_eq!(debug_string(to.sabi_reborrow()), "13");
assert_eq!(debug_string(to.sabi_reborrow()), "13");

fn debug_string<T>(to: T) -> String
where
    T: std::fmt::Debug,
{
    format!("{:?}", to)
}

pub fn reborrow_mut<'re>(&'re mut self) -> RObject<'lt, RMut<'re, ()>, I, V>

where P: AsMutPtr<PtrTarget = ()>, PrivStruct: ReborrowBounds<I::Send, I::Sync>,

Creates a mutable reborrow of this RObject.

The reborrowed RObject cannot use these methods:

• RObject::clone

This is only callable if RObject is either Send + Sync or !Send + !Sync.

Example

use abi_stable::{
    sabi_trait::doc_examples::{Doer, Doer_TO},
    std_types::RBox,
    type_level::downcasting::TD_Opaque,
    RMut, RRef,
};

let mut to: Doer_TO<'_, RBox<()>> = Doer_TO::from_value(2usize, TD_Opaque);

// `#[sabi_trait]` trait objects have an equivalent `sabi_reborrow_mut` method,
// which delegate to this method.
assert_eq!(increment(to.sabi_reborrow_mut()).value(), 3);
assert_eq!(increment(to.sabi_reborrow_mut()).value(), 4);

fn increment<T>(mut to: T) -> T
where
    T: Doer,
{
    to.add_into(1);
    to
}

impl<'lt, P, I, V> RObject<'lt, P, I, V>

where P: GetPointerKind,

pub const fn sabi_et_vtable(&self) -> PrefixRef<V>

Gets the vtable.

pub fn sabi_robject_vtable(&self) -> RObjectVtable_Ref<(), P, I>

The vtable common to all #[sabi_trait] generated trait objects.

pub fn sabi_erased_ref(&self) -> RRef<'_, ErasedObject<()>>

where P: AsPtr<PtrTarget = ()>,

Gets an RRef pointing to the erased object.

pub fn sabi_erased_mut(&mut self) -> RMut<'_, ErasedObject<()>>

where P: AsMutPtr<PtrTarget = ()>,

Gets an RMut pointing to the erased object.

pub fn sabi_as_rref(&self) -> RRef<'_, ()>

where P: AsPtr<PtrTarget = ()>,

Gets an RRef pointing to the erased object.

pub fn sabi_as_rmut(&mut self) -> RMut<'_, ()>

where P: AsMutPtr<PtrTarget = ()>,

Gets an RMut pointing to the erased object.

pub fn sabi_with_value<F, R>(self, f: F) -> R

where P: OwnedPointer<PtrTarget = ()>, F: FnOnce(MovePtr<'_, ()>) -> R,

Calls the f callback with an MovePtr pointing to the erased object.

impl<'lt, I, V> RObject<'lt, RArc<()>, I, V>

pub fn shallow_clone(&self) -> Self

Does a shallow clone of the object, just incrementing the reference counter

Trait Implementations

impl<'lt, P, I, V> Clone for RObject<'lt, P, I, V>

where P: AsPtr, I: InterfaceType, Self: CloneImpl<<P as GetPointerKind>::Kind>,

Clone is implemented for references and smart pointers, using GetPointerKind to decide whether P is a smart pointer or a reference.

RObject does not implement Clone if P == &mut () :

use abi_stable::{
    sabi_trait::{doc_examples::ConstExample_TO, TD_Opaque},
    std_types::*,
};

let mut object = ConstExample_TO::from_value(10usize, TD_Opaque);
let borrow = object.sabi_reborrow_mut();
let _ = borrow.clone();

Here is the same example with sabi_reborrow

use abi_stable::{
    sabi_trait::{doc_examples::ConstExample_TO, TD_Opaque},
    std_types::*,
};

let mut object = ConstExample_TO::from_value(10usize, TD_Opaque);
let borrow = object.sabi_reborrow();
let _ = borrow.clone();

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'lt, P, I, V> Debug for RObject<'lt, P, I, V>

where P: AsPtr<PtrTarget = ()> + AsPtr, I: InterfaceType<Debug = Implemented<Debug>>,

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

Formats the value using the given formatter.

impl<'lt, P, I, V> Display for RObject<'lt, P, I, V>

where P: AsPtr<PtrTarget = ()>, I: InterfaceType<Display = Implemented<Display>>,

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

Formats the value using the given formatter.

impl<P, I, V> Drop for RObject<'_, P, I, V>

where P: GetPointerKind,

fn drop(&mut self)

Executes the destructor for this type.

impl<'lt, P, I, V> Error for RObject<'lt, P, I, V>

where P: AsPtr<PtrTarget = ()>, I: InterfaceType<Display = Implemented<Display>, Debug = Implemented<Debug>, Error = Implemented<Error>>,

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl<'lt, P, I, V> GetStaticEquivalent_ for RObject<'lt, P, I, V>

where P: GetPointerKind + __StableAbi, I: __StableAbi + InterfaceType, V: __GetStaticEquivalent_ + PrefixStableAbi,

type StaticEquivalent = _static_RObject<'static, <P as GetStaticEquivalent_>::StaticEquivalent, <I as GetStaticEquivalent_>::StaticEquivalent, <V as GetStaticEquivalent_>::StaticEquivalent>

The 'static equivalent of Self

impl<'lt, P, I, V> StableAbi for RObject<'lt, P, I, V>

where P: GetPointerKind + __StableAbi, I: __StableAbi + InterfaceType, V: __GetStaticEquivalent_ + PrefixStableAbi,

type IsNonZeroType = False

Whether this type has a single invalid bit-pattern.

const LAYOUT: &'static TypeLayout = _

The layout of the type provided by implementors.

const ABI_CONSTS: AbiConsts = _

const-equivalents of the associated types.

impl<'lt, P, I, V> Send for RObject<'lt, P, I, V>

where P: GetPointerKind, I: InterfaceType<Send = Implemented<Send>>,

impl<'lt, P, I, V> Sync for RObject<'lt, P, I, V>

where P: GetPointerKind, I: InterfaceType<Sync = Implemented<Sync>>,

impl<'lt, P, I, V> Unpin for RObject<'lt, P, I, V>

where P: GetPointerKind, I: InterfaceType<Unpin = Implemented<Unpin>>,