Struct abi_stable::VirtualWrapper

#[repr(C)]
pub struct VirtualWrapper<P> { /* fields omitted */ }

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

Passing opaque values around with VirtualWrapper<_>

One can pass non-StableAbi types around by using type erasure,using this type.

It generally looks like VirtualWrapper<Pointer<ZeroSized<Interface>>>,where:

• Pointer is some pointer_trait::StableDeref pointer type.

• ZeroSized is a zero-sized marker type.

• Interface is an InterfaceType,which describes what traits are required when constructing the VirtualWrapper<_> and which ones it implements.

trait InterfaceType allows describing which traits are required when constructing a VirtualWrapper<_>,and which ones it implements.

Construction

To construct a VirtualWrapper<_> one can use these associated functions:

• from_value: Can be constructed from the value directly. Requires a value that implements ImplType.

• from_ptr: Can be constructed from a pointer of a value. Requires a value that implements ImplType.

• from_any_value: Can be constructed from the value directly.Requires a 'static value.

• from_any_ptr Can be constructed from a pointer of a value.Requires a 'static value.

Trait object

VirtualWrapper<Pointer<ZeroSized< Interface >>> can be used as a trait object for any combination of the traits listed bellow.

These are the traits:

• Clone

• Display

• Debug

• Default: Can be called as an inherent method.

• Eq

• PartialEq

• Ord

• PartialOrd

• Hash

• serde::Deserialize: first deserializes from a string,and then calls the objects' Deserialize impl.

• serde::Serialize: first calls the objects' Deserialize impl,then serializes that as a string.

Deconstruction

VirtualWrapper<_> can then 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. Where VirtualWrapper<P<ZeroSized< Interface >>>'s Interface must equal <T as ImplType>::Interface

• as_unerased: Unwraps into a &T. Where VirtualWrapper<P<ZeroSized< Interface >>>'s Interface must equal <T as ImplType>::Interface

• as_unerased_mut: Unwraps into a &mut T. Where VirtualWrapper<P<ZeroSized< Interface >>>'s Interface must equal <T as ImplType>::Interface

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

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

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

Methods

impl VirtualWrapper<()>

pub fn from_value<T>(object: T) -> VirtualWrapper<RBox<ZeroSized<T::Interface>>> where
    T: ImplType,
    T: GetVtable<T, RBox<ZeroSized<<T as ImplType>::Interface>>, RBox<T>>, 

Constructors the VirtualWrapper<_> from an ImplType implementor.

Use this whenever possible instead of from_any_value, because it produces better error messages when unerasing the VirtualWrapper<_>

pub fn from_ptr<P, T>(object: P) -> VirtualWrapper<P::TransmutedPtr> where
    P: StableDeref<Target = T>,
    T: ImplType,
    T: GetVtable<T, P::TransmutedPtr, P>,
    P: ErasedStableDeref<<T as ImplType>::Interface>, 

Constructors the VirtualWrapper<_> from a pointer to an ImplType implementor.

Use this whenever possible instead of from_any_ptr, because it produces better error messages when unerasing the VirtualWrapper<_>

pub fn from_any_value<T, I>(
    object: T,
    interface: I
) -> VirtualWrapper<RBox<ZeroSized<I>>> where
    T: 'static,
    I: InterfaceType,
    InterfaceFor<T, I>: GetVtable<T, RBox<ZeroSized<I>>, RBox<T>>, 

Constructors the VirtualWrapper<_> from a type which doesn't borrow anything.

pub fn from_any_ptr<P, T, I>(
    object: P,
    _interface: I
) -> VirtualWrapper<P::TransmutedPtr> where
    I: InterfaceType,
    P: StableDeref<Target = T>,
    T: 'static,
    InterfaceFor<T, I>: GetVtable<T, P::TransmutedPtr, P>,
    P: ErasedStableDeref<I>, 

Constructors the VirtualWrapper<_> from a pointer to a type which doesn't borrow anything.

impl<P> VirtualWrapper<P>

pub fn is_same_type<Other>(&self, other: &VirtualWrapper<Other>) -> bool

Allows checking whether 2 VirtualWrapper<_>s have a value of the same type.

Note that types from different dynamic libraries/executables are never considered equal.

pub fn object_address(&self) -> usize where
    P: Deref, 

Returns the address of the wrapped object.

This will not change between calls for the same VirtualWrapper<_>.

impl<P> VirtualWrapper<P>

pub fn into_unerased<T>(self) -> Result<P::TransmutedPtr, UneraseError> where
    P: TransmuteElement<T>,
    P::Target: Sized,
    T: ImplType + GetVtable<T, P, P::TransmutedPtr>, 

Unwraps the VirtualWrapper<_> into a pointer of the concrete type that it was constructed with.

T is required to implement ImplType.

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 VirtualWrapper<_> was constructed.

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

pub fn as_unerased<T>(&self) -> Result<&T, UneraseError> where
    P: Deref + TransmuteElement<T>,
    T: ImplType + GetVtable<T, P, P::TransmutedPtr>, 

Unwraps the VirtualWrapper<_> into a reference of the concrete type that it was constructed with.

T is required to implement ImplType.

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 VirtualWrapper<_> was constructed.

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

pub fn as_unerased_mut<T>(&mut self) -> Result<&mut T, UneraseError> where
    P: DerefMut + TransmuteElement<T>,
    T: ImplType + GetVtable<T, P, P::TransmutedPtr>, 

Unwraps the VirtualWrapper<_> into a mutable reference of the concrete type that it was constructed with.

T is required to implement ImplType.

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 VirtualWrapper<_> was constructed.

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

pub fn into_any_unerased<T>(self) -> Result<P::TransmutedPtr, UneraseError> where
    P: TransmuteElement<T>,
    P::Target: Sized,
    Self: VirtualWrapperTrait,
    InterfaceFor<T, GetVWInterface<Self>>: GetVtable<T, P, P::TransmutedPtr>, 

Unwraps the VirtualWrapper<_> into a pointer of the concrete type that it was constructed with.

T is required to not borrows anything.

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 VirtualWrapper<_> was constructed.

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

pub fn as_any_unerased<T>(&self) -> Result<&T, UneraseError> where
    P: Deref + TransmuteElement<T>,
    Self: VirtualWrapperTrait,
    InterfaceFor<T, GetVWInterface<Self>>: GetVtable<T, P, P::TransmutedPtr>, 

Unwraps the VirtualWrapper<_> into a reference of the concrete type that it was constructed with.

T is required to not borrows anything.

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 VirtualWrapper<_> was constructed.

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

pub fn as_any_unerased_mut<T>(&mut self) -> Result<&mut T, UneraseError> where
    P: DerefMut + TransmuteElement<T>,
    Self: VirtualWrapperTrait,
    InterfaceFor<T, GetVWInterface<Self>>: GetVtable<T, P, P::TransmutedPtr>, 

Unwraps the VirtualWrapper<_> into a mutable reference of the concrete type that it was constructed with.

T is required to not borrows anything.

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 VirtualWrapper<_> was constructed.

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

impl<P> VirtualWrapper<P>

pub fn default<I>(&self) -> Self where
    P: Deref<Target = ZeroSized<I>>,
    I: InterfaceType<Default = True>, 

Constructs a VirtualWrapper<P> with the default value for P.

pub fn serialized<'a, I>(&'a self) -> Result<RCow<'a, RStr<'a>>, RBoxError> where
    P: Deref<Target = ZeroSized<I>>,
    I: InterfaceType<Serialize = True>, 

It serializes a VirtualWrapper<_> into a string by using <ConcreteType as SerializeImplType>::serialize_impl.

pub fn deserialize_from_str<'a, I>(s: &'a str) -> Result<Self, RBoxError> where
    P: Deref<Target = ZeroSized<I>>,
    I: DeserializeInterfaceType<Deserialize = True, Deserialized = Self>, 

Deserializes a string into a VirtualWrapper<_>,by using <I as DeserializeInterfaceType>::deserialize_impl.

Trait Implementations

impl<P> SharedStableAbi for VirtualWrapper<P> where
    P: __StableAbi, 

type IsNonZeroType = False

Whether this type has a single invalid bit-pattern.

type Kind = __ValueKind

The kind of abi stability of this type,there are 2:

type StaticEquivalent = VirtualWrapper<__StaticEquivalent<P>>

A version of the type which does not borrow anything, used to create a UTypeId for doing layout checking.

const S_LAYOUT: &'static TypeLayout

The layout of the type provided by implementors.

const S_ABI_INFO: &'static AbiInfoWrapper

The layout of the type,derived from Self::LAYOUT and associated types.

impl<P, I> VirtualWrapperTrait for VirtualWrapper<P> where
    P: Deref<Target = ZeroSized<I>>,
    I: InterfaceType, 

type Interface = I

impl<P, I> Eq for VirtualWrapper<P> where
    Self: PartialEq,
    P: Deref<Target = ZeroSized<I>>,
    I: InterfaceType<Eq = True>, 

impl<P, I> PartialOrd<VirtualWrapper<P>> for VirtualWrapper<P> where
    P: Deref<Target = ZeroSized<I>>,
    I: InterfaceType<PartialOrd = True>,
    Self: PartialEq, 

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

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

#[must_use]

fn lt(&self, other: &Rhs) -> bool

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

#[must_use]

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]

fn gt(&self, other: &Rhs) -> bool

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

#[must_use]

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<P, I> PartialEq<VirtualWrapper<P>> for VirtualWrapper<P> where
    P: Deref<Target = ZeroSized<I>>,
    I: InterfaceType<PartialEq = True>, 

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

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

#[must_use]

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<P, I> Clone for VirtualWrapper<P> where
    P: Deref<Target = ZeroSized<I>>,
    I: InterfaceType<Clone = True>, 

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<P, I> Ord for VirtualWrapper<P> where
    P: Deref<Target = ZeroSized<I>>,
    I: InterfaceType<Ord = True>,
    Self: PartialOrd + Eq, 

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

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

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

Restrict a value to a certain interval.

impl<P> Drop for VirtualWrapper<P>

fn drop(&mut self)

Executes the destructor for this type.

impl<P, I> Display for VirtualWrapper<P> where
    P: Deref<Target = ZeroSized<I>>,
    I: InterfaceType<Display = True>, 

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

Formats the value using the given formatter.

impl<P, I> Debug for VirtualWrapper<P> where
    P: Deref<Target = ZeroSized<I>>,
    I: InterfaceType<Debug = True>, 

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

Formats the value using the given formatter.

impl<P, I> Hash for VirtualWrapper<P> where
    P: Deref<Target = ZeroSized<I>>,
    I: InterfaceType<Hash = True>, 

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, 

Feeds a slice of this type into the given [Hasher].

impl<'a, P, I> Deserialize<'a> for VirtualWrapper<P> where
    P: Deref<Target = ZeroSized<I>>,
    I: DeserializeInterfaceType<Deserialize = True, Deserialized = Self>, 

First it Deserializes a string,then it deserializes into a VirtualWrapper<_>,by using <I as DeserializeInterfaceType>::deserialize_impl.

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error> where
    D: Deserializer<'a>, 

Deserialize this value from the given Serde deserializer.

impl<P, I> Serialize for VirtualWrapper<P> where
    P: Deref<Target = ZeroSized<I>>,
    I: InterfaceType<Serialize = True>, 

First it serializes a VirtualWrapper<_> into a string by using ::serialize_impl, then it serializes the string. ,then it .

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> where
    S: Serializer, 

Serialize this value into the given Serde serializer.