Skip to main content

TokenTrait

token_cell::core

Trait TokenTrait 

Source 
pub trait TokenTrait: Sized {
    type ComparisonMaySpuriouslyEq: Boolean;
    type RunError;
    type Identifier;
    type ComparisonError;
    type Branded<'a>;

    // Required methods
    fn with_token<R, F: for<'a> FnOnce(Self::Branded<'a>) -> R>(
        f: F,
    ) -> Result<R, Self::RunError>;
    fn identifier(&self) -> Self::Identifier;
    fn compare(
        &self,
        id: &Self::Identifier,
    ) -> Result<(), Self::ComparisonError>;
}
Expand description

A trait for tokens

Required Associated Types§

Source

type ComparisonMaySpuriouslyEq: Boolean

Whether or not comparison between two distinct token could yield eq.

This can be the case for tokens that can be constructed with UnscopedToken an arbitrary amount of times, but aren’t guaranteed to have unique identifiers distinguishing them:

  • Instances of the types created by unsafe_token, for example, are indistinguishable at both compile and runtime; accidentally using two distinct instances to gain access to a same cell could cause undefined behaviour if done simultaneously.
  • Instances of the types created by runtime_token are identified by a cyclic counter (`u16`` by default); while unlikely, you could create two distinct instances with a same internal id by overflowing the static counter used to construct them.
Source

type RunError

TokenTrait::with_token may fail, typically if construction failed.

Some types, like GhostToken are inconstructible with UnscopedToken, but cannot fail to run, hence the distinction.

Source

type Identifier

Lets a TokenCell keep track of the token.

In most cases, this is a ZST in release mode.

Source

type ComparisonError

core::convert::Infallible unless TokenTrait::compare is fallible (ie. comparison is done at runtime).

Source

type Branded<'a>

Rebrands the token, this is necessary for GhostToken to function properly

Required Methods§

Source

fn with_token<R, F: for<'a> FnOnce(Self::Branded<'a>) -> R>( f: F, ) -> Result<R, Self::RunError>

Constructs a new, lifetime-branded Token, and provides it to the closure.

This is especially useful for GhostToken, which can only be constructed that way, as they use lifetimes to obtain a unique brand.

§Errors

If construction failed, so will this.

Source

fn identifier(&self) -> Self::Identifier

Returns the Token’s identifier, which cells may store to allow comparison.

Source

fn compare(&self, id: &Self::Identifier) -> Result<(), Self::ComparisonError>

Allows the cell to compare its identifier to the Token.

§Errors

If a wrong token was mistakenly passed to the cell.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§