Struct singleton_trait::Erased

pub struct Erased<T> { /* private fields */ }

The Erased struct witnesses the logical ownership of a value of type T while remaining zero-sized. This can be used for ghost proofs of soundness.

Erased should be thought of a zero-sized owner of T. It is useful for inclusion in data structures where the value might not be eliminated by the compiler. It likely is not necessary for short-lived data.

NOTE: drop implementations will never be called, as Exists guarantees the existence of a valid T, which might not be true if they were called. On the other hand, since it does not hold a T, it cannot drop T when it is itself dropped

Secondly, keep in mind that while Erased serves as evidence, it does not include sufficient provenance for Stacked Borrows or LLVM, and so it is not techinically sound to recover a reference &T from an Exists<&T> and *mut T or &UnsafeCell<T> even when T is Singleton, but this could be possible if T is zero-sized. Because of the missing provenance, creating a reference this way could invalidate the original reference on which this Exists instance was based.

Implementations

impl<T> Erased<T>

pub const fn new(t: T) -> Self

pub const unsafe fn new_unchecked() -> Self

This function constructs a value of Erased without taking logical ownership of a T.

Safety

Constructing this asserts that there is a value of type T which has been leaked, or in which it is guaranteed that the program behaves the same up to observation as if a zero-sized copy of T were being passed.

pub fn borrow(&self) -> Erased<&T>

Turns a &Erased into an Erased<&T>

This can be especially useful when storing the Erased inside another wrapper type

use core::cell::RefCell;
struct Token;
let lock = RefCell::new(Erased::new(Token));

let locked = lock.borrow();
let _: Erased<&Token> = locked.borrow();

pub fn borrow_mut(&mut self) -> Erased<&mut T>

Turns a &mut Erased into an Erased<&mut T>

This can be especially useful when storing the Erased inside another wrapper type

use core::cell::RefCell;
struct Token;
let lock = RefCell::new(Erased::new(Token));

let mut locked = lock.borrow_mut();
let _: Erased<&mut Token> = locked.borrow_mut();

pub unsafe fn map<R, F: FnOnce(T) -> R>(self, _: impl Exists<F>) -> Erased<R>

Maps a function on the inside of the Erased field.

Safety

Due to the strictness guarantees, the passed closure must not cause any visible side effects, including side effects caused by owning R

pub unsafe fn map_borrow<'a, R, F: FnOnce(&'a T) -> R>(
    &'a self,
    _: impl Exists<F>
) -> Erased<R>

Maps a function on the borrow of the Erased field.

Safety

Due to the strictness guarantees, the passed closure must not cause any visible side effects, including side effects caused by owning R

pub unsafe fn map_borrow_mut<'a, R, F: FnOnce(&'a mut T) -> R>(
    &'a mut self,
    _: impl Exists<F>
) -> Erased<R>

Maps a function on the mutable borrow of the Erased field.

Safety

Due to the strictness guarantees, the passed closure must not cause any visible side effects, including side effects caused by owning R

pub fn exists(self) -> impl Exists<T>

Fallback function which converts this Erased value into an Exists implementer.

This exists because we cannot allow general trait implementations due to coherence rules, but we can’t be sufficiently flexible in trait implementations due to a lack of subtyping constraints or trait covariance, which would mean references would be too inflexible

impl<T> Erased<Erased<T>>

pub fn flatten(self) -> Erased<T>

An erased erased value can be flattened into a single erasure, since Erased is notionally equivalent to T

impl<'a, T> Erased<&'a mut T>

pub fn reborrow<'b>(&'b mut self) -> Erased<&'b mut T>

Re-borrow this erased mutable borrow. Usually this is implicit in Rust, but not for general wrappers. This can be seen as a “clone” method for mutable borrows, as it allows you to retain the erased borrow after the end of the lifetime.

The Exists trait can perform this conversion automatically.

struct Token;
fn recursively(mut b: Erased<&mut Token>) {
 recursively(b.reborrow());
 recursively(b);
}

pub fn read<'b>(&'b self) -> Erased<&'b T>

Borrow this erased mutable borrow as immutable. This is effectively a Deref method under Erased

The Exists trait can perform this conversion automatically.

struct Lock;
fn use_lock(write: Erased<&mut Lock>) {
  read_from(write.read());
}

fn read_from(read: Erased<&Lock>) { }

pub fn into_shared(self) -> Erased<&'a T>

Consume this erased mutable borrow to turn it into an immutable borrow.

The Exists trait can perform this conversion automatically.

See also read, which is often more useful. This method uses the full inner lifetime without needing to borrow.

struct Lock;
struct MutWrapper<'a> (Erased<&'a mut Lock>);
struct Wrapper<'a> (Erased<&'a Lock>);
impl<'a> MutWrapper<'a> {
  pub fn into_read(self) -> Wrapper<'a> {
     Wrapper(self.0.into_shared())
  }
}

Trait Implementations

impl<T: Copy> Clone for Erased<T>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a, 'b: 'a, T> Exists<&'a T> for Erased<&'b T>

fn erase(self) -> Erased<&'a T>

impl<'a, 'b: 'a, T> Exists<&'a T> for Erased<&'b mut T>

fn erase(self) -> Erased<&'a T>

impl<'a, 'b, T> Exists<&'a T> for &'a Erased<&'b T>

fn erase(self) -> Erased<&'a T>

impl<'a, 'b: 'a, T> Exists<&'a T> for &'a Erased<&'b mut T>

fn erase(self) -> Erased<&'a T>

impl<'a, 'b: 'a, T> Exists<&'a mut T> for Erased<&'b mut T>

fn erase(self) -> Erased<&'a mut T>

impl<'a, 'b: 'a, T> Exists<&'a mut T> for &'a mut Erased<&'b mut T>

fn erase(self) -> Erased<&'a mut T>

impl<T> From<T> for Erased<T>

fn from(t: T) -> Self

Converts to this type from the input type.

impl<T: Copy> Copy for Erased<T>

impl<'a, T: SingleThread> SingleThread for Erased<T>

impl<'a, T: Singleton> Singleton for Erased<T>