Struct abi_stable::sabi_trait::RObject [−][src]
#[repr(C)]pub struct RObject<'lt, P, I, V> where
P: GetPointerKind, { /* fields omitted */ }
Expand description
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
-
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 toT
.RequiresT: 'static
. -
downcast_as
: Unwraps into a&T
.RequiresT: 'static
. -
downcast_as_mut
: Unwraps into a&mut T
.RequiresT: 'static
.
RObject
can only be converted back if the trait object was constructed to allow it.
Implementations
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 = ()>,
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 usingRObject::reborrow
orRObject::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
pub const unsafe fn with_vtable_const<T, Downcasting>(
ptr: &'a T,
vtable: VTableTO_RO<T, RRef<'a, T>, Downcasting, V>
) -> Self where
T: 'borr,
pub const unsafe fn with_vtable_const<T, Downcasting>(
ptr: &'a T,
vtable: VTableTO_RO<T, RRef<'a, T>, Downcasting, 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::TD_Opaque,
};
const EXAMPLE0: ConstExample_CTO<'static, 'static> =
ConstExample_CTO::from_const(&0usize, TD_Opaque, ConstExample_MV::VTABLE);
pub fn downcast_into<T>(self) -> Result<P::TransmutedPtr, UneraseError<Self>> where
T: 'static,
P: AsPtr<PtrTarget = ()> + CanTransmuteElement<T>,
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 aTD_CanDowncast
argument. -
T
is not the concrete type thisRObject<_>
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>,
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 aTD_CanDowncast
argument. -
T
is not the concrete type thisRObject<_>
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>,
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 aTD_CanDowncast
argument. -
T
is not the concrete type thisRObject<_>
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>,
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)
);
}
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 = ()>,
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);
}
}
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>,
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
}
Gets the vtable.
The vtable common to all #[sabi_trait]
generated trait objects.
Gets an RRef
pointing to the erased object.
pub fn sabi_erased_mut(&mut self) -> RMut<'_, ErasedObject<()>> where
P: AsMutPtr<PtrTarget = ()>,
pub fn sabi_erased_mut(&mut self) -> RMut<'_, ErasedObject<()>> where
P: AsMutPtr<PtrTarget = ()>,
Gets an RMut
pointing to the erased object.
Gets an RRef
pointing to the erased object.
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,
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.
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>,
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();
impl<'lt, P, I, V> Debug for RObject<'lt, P, I, V> where
P: AsPtr<PtrTarget = ()> + AsPtr,
I: InterfaceType<Debug = Implemented<Debug>>,
impl<'lt, P, I, V> Debug for RObject<'lt, P, I, V> where
P: AsPtr<PtrTarget = ()> + AsPtr,
I: InterfaceType<Debug = Implemented<Debug>>,
impl<'lt, P, I, V> Display for RObject<'lt, P, I, V> where
P: AsPtr<PtrTarget = ()>,
I: InterfaceType<Display = Implemented<Display>>,
impl<'lt, P, I, V> Display for RObject<'lt, P, I, V> where
P: AsPtr<PtrTarget = ()>,
I: InterfaceType<Display = Implemented<Display>>,
impl<'lt, P, I, V> Error for RObject<'lt, P, I, V> where
P: AsPtr<PtrTarget = ()>,
I: InterfaceBound<Display = Implemented<Display>, Debug = Implemented<Debug>, Error = Implemented<Error>>,
impl<'lt, P, I, V> Error for RObject<'lt, P, I, V> where
P: AsPtr<PtrTarget = ()>,
I: InterfaceBound<Display = Implemented<Display>, Debug = Implemented<Debug>, Error = Implemented<Error>>,
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,
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> StableAbi for RObject<'lt, P, I, V> where
P: GetPointerKind,
P: __StableAbi,
I: __StableAbi,
V: __GetStaticEquivalent_,
V: PrefixStableAbi,
I: InterfaceBound,
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
type IsNonZeroType = False
Whether this type has a single invalid bit-pattern. Read more
The layout of the type provided by implementors.
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>>,
Auto Trait Implementations
impl<'lt, P, I, V> RefUnwindSafe for RObject<'lt, P, I, V> where
I: RefUnwindSafe,
P: RefUnwindSafe,
V: RefUnwindSafe,
impl<'lt, P, I, V> UnwindSafe for RObject<'lt, P, I, V> where
I: UnwindSafe,
P: UnwindSafe,
V: RefUnwindSafe,
Blanket Implementations
Mutably borrows from an owned value. Read more
type ROwned = T
type ROwned = T
The owned type, stored in RCow::Owned
type ForSelf = WithMetadata_<T, T>
type ForSelf = WithMetadata_<T, T>
This is always WithMetadata_<Self, Self>
Compares the address of self
with the address of other
. Read more
Emulates the pipeline operator, allowing method syntax in more places. Read more
The same as piped
except that the function takes &Self
Useful for functions that take &Self
instead of Self
. Read more
The same as piped
, except that the function takes &mut Self
.
Useful for functions that take &mut Self
instead of Self
. Read more
Mutates self using a closure taking self by mutable reference, passing it along the method chain. Read more
Observes the value of self, passing it along unmodified. Useful in long method chains. Read more
Performs a conversion with Into
.
using the turbofish .into_::<_>()
syntax. Read more
Performs a reference to reference conversion with AsRef
,
using the turbofish .as_ref_::<_>()
syntax. Read more
Performs a mutable reference to mutable reference conversion with AsMut
,
using the turbofish .as_mut_::<_>()
syntax. Read more
unsafe fn transmute_element<T>(
self
) -> <Self as CanTransmuteElement<T>>::TransmutedPtr where
Self: CanTransmuteElement<T>,
unsafe fn transmute_element<T>(
self
) -> <Self as CanTransmuteElement<T>>::TransmutedPtr where
Self: CanTransmuteElement<T>,
Transmutes the element type of this pointer.. Read more
type Type = T
type Type = T
This is always Self
.
Converts a value back to the original type.
Converts a mutable reference back to the original type.
alloc
only.Converts a box back to the original type.
Converts a value back to the original type.
Converts a reference back to the original type.
Converts a mutable reference back to the original type.
alloc
only.Converts a box back to the original type.
alloc
only.Converts an Arc back to the original type.
alloc
only.Converts an Rc back to the original type.