Struct abi_stable::sabi_trait::RObject

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

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.

These are the traits:

• Send

• Sync

• 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:

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

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

• as_unerased_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: GetPointerKind<Target = ()>, 

pub unsafe fn with_vtable<OrigPtr>(
    ptr: OrigPtr,
    vtable: PrefixRef<V>
) -> RObject<'lt, P, I, V> where
    OrigPtr: CanTransmuteElement<(), TransmutedPtr = P>,
    OrigPtr::Target: Sized + 'lt,
    P: Deref<Target = ()>, 

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, Unerasability>(
    ptr: &'a T,
    vtable: VTableTO_RO<T, RRef<'a, T>, Unerasability, 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,ConstExample_MV},
    prelude::TU_Opaque,
};

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

impl<'lt, P, I, V> RObject<'lt, P, I, V> where
    P: GetPointerKind, 

pub fn into_unerased<T>(self) -> Result<P::TransmutedPtr, UneraseError<Self>> where
    T: 'static,
    P: Deref<Target = ()> + 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 TU_Unerasable argument.

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

pub fn as_unerased<T>(&self) -> Result<&T, UneraseError<&Self>> where
    T: 'static,
    P: Deref<Target = ()> + 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 TU_Unerasable argument.

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

pub fn as_unerased_mut<T>(&mut self) -> Result<&mut T, UneraseError<&mut Self>> where
    T: 'static,
    P: DerefMut<Target = ()> + 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 TU_Unerasable argument.

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

pub unsafe fn unchecked_into_unerased<T>(self) -> P::TransmutedPtr where
    P: Deref<Target = ()> + 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.

pub unsafe fn unchecked_as_unerased<T>(&self) -> &T where
    P: Deref<Target = ()>, 

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.

pub unsafe fn unchecked_as_unerased_mut<T>(&mut self) -> &mut T where
    P: DerefMut<Target = ()>, 

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.

impl<'lt, P, I, V> RObject<'lt, P, I, V> where
    P: GetPointerKind,
    I: InterfaceType, 

pub fn reborrow<'re>(&'re self) -> RObject<'lt, &'re (), I, V> where
    P: Deref<Target = ()>,
    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.

pub fn reborrow_mut<'re>(&'re mut self) -> RObject<'lt, &'re mut (), I, V> where
    P: DerefMut<Target = ()>,
    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.

impl<'lt, P, I, V> RObject<'lt, P, I, V> where
    P: GetPointerKind, 

pub 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) -> &ErasedObject<()> where
    P: __DerefTrait<Target = ()>, 

Gets an RRef pointing to the erased object.

pub fn sabi_erased_mut(&mut self) -> &mut ErasedObject<()> where
    P: __DerefMutTrait<Target = ()>, 

Gets an RMut pointing to the erased object.

pub fn sabi_as_rref(&self) -> RRef<'_, ()> where
    P: __DerefTrait<Target = ()>, 

Gets an RRef pointing to the erased object.

pub fn sabi_as_rmut(&mut self) -> RMut<'_, ()> where
    P: __DerefMutTrait<Target = ()>, 

Gets an RMut pointing to the erased object.

pub fn sabi_with_value<F, R>(self, f: F) -> R where
    P: OwnedPointer<Target = ()>,
    F: FnOnce(MovePtr<'_, ()>) -> R, 

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

Trait Implementations

impl<'lt, P, I, V> Clone for RObject<'lt, P, I, V> where
    P: Deref + GetPointerKind,
    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,
        TU_Opaque,
    },
    std_types::*,
};

let mut object=ConstExample_TO::from_value(10usize,TU_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,
        TU_Opaque,
    },
    std_types::*,
};

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

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<'lt, P, I, V> Debug for RObject<'lt, P, I, V> where
    P: Deref<Target = ()> + GetPointerKind,
    I: InterfaceType<Debug = Implemented<Debug>>, 

pub 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: Deref<Target = ()> + GetPointerKind,
    I: InterfaceType<Display = Implemented<Display>>, 

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

pub fn drop(&mut self)

Executes the destructor for this type.

impl<'lt, P, I, V> Error for RObject<'lt, P, I, V> where
    P: Deref<Target = ()> + GetPointerKind,
    I: InterfaceBound<Display = Implemented<Display>, Debug = Implemented<Debug>, Error = Implemented<Error>>, 

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

The lower-level source of this error, if any.

pub fn backtrace(&self) -> Option<&Backtrace>

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

Returns a stack backtrace, if available, of where this error occurred.

pub fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

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

👎 Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

impl<'lt, P, I, V> GetStaticEquivalent_ for RObject<'lt, P, I, V> where
    P: GetPointerKind,
    P: __StableAbi,
    I: __StableAbi,
    V: __GetStaticEquivalent_,
    V: PrefixStableAbi,
    I: InterfaceBound, 

type StaticEquivalent = _static_RObject<'static, __GetStaticEquivalent<P>, __GetStaticEquivalent<I>, __GetStaticEquivalent<V>>

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> StableAbi for RObject<'lt, P, I, V> where
    P: GetPointerKind,
    P: __StableAbi,
    I: __StableAbi,
    V: __GetStaticEquivalent_,
    V: PrefixStableAbi,
    I: InterfaceBound, 

type IsNonZeroType = False

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<'lt, P, I, V> Sync for RObject<'lt, P, I, V> where
    P: GetPointerKind,
    I: InterfaceType<Sync = Implemented<Sync>>,