Struct tokenlock::SingletonToken

pub struct SingletonToken<Tag: ?Sized, Variant = SyncVariant>(_);

A singleton unforgeable token used to access the contents of a TokenLock.

It's a singleton object, meaning there can be only one instance of SingletonToken<Tag> for each specific Tag. The instances of SingletonToken are solely distinguished by its type parameter Tag, making this type zero-sized.

This type lacks a Clone implementation to ensure exclusive access to TokenLock.

This type is invariant over Tag.

The second type parameter (Variant) is internal use only and exempt from the API stability guarantee.

Sync-ness Conversion

SingletonToken can be converted back and forth to its non-Sync variation, UnsyncSingletonToken, by the following methods:

		To Sync	To !Sync
Sync	&mut	borrow_mut	borrow_unsync_mut
	&	borrow	†
	owned		into_unsync
!Sync	&mut	borrow_sync_mut	borrow_mut
	&	borrow_sync	borrow
	owned	into_sync

† borrow_unsync doesn't exist because &SingletonToken (the Sync variation) might already be owned by multiple threads, so converting them to the !Sync variation would violate the !Sync requirement.

The non-Sync variation can be used to access the contents of UnsyncTokenLock.

Implementations

impl<Tag: ?Sized + SingletonTokenFactory, Variant: SingletonTokenVariant> SingletonToken<Tag, Variant>

pub fn new(
) -> Result<SingletonTokenGuard<Tag, Variant>, SingletonTokenExhaustedError>

Construct Self, using Tag's SingletonTokenFactory implementation to ensure only one token is present at once.

Returns an RAII guard that derefs to SingletonToken and returns the token when dropped.

Examples

struct MyTag;
impl_singleton_token_factory!(MyTag);

type MyTokenLock<T> = TokenLock<T, SingletonTokenId<MyTag>>;
type MyToken = SingletonToken<MyTag>;
type MyTokenId = SingletonTokenId<MyTag>;

static LOCK1: MyTokenLock<u32> = MyTokenLock::new(MyTokenId::new(), 1);
static LOCK2: MyTokenLock<u32> = MyTokenLock::new(MyTokenId::new(), 1);

// Create a singleton token with a runtime uniqueness check
let mut token = MyToken::new().unwrap();

LOCK1.read(&*token);
LOCK2.write(&mut *token);

The SingletonTokenFactory implementation remembers that a token has been issued, so attempts to issue two tokens of the same tag will fail:

let token = SingletonToken::<MyTag>::new().unwrap();
assert!(SingletonToken::<MyTag>::new().is_err());

impl<Tag: ?Sized, Variant> SingletonToken<Tag, Variant>

pub const unsafe fn new_unchecked() -> Self

Construct Self without checking the singleton invariant.

Safety

Having more than one instance of SingletonToken<Tag> for a particular Tag violates Token's requirements and allows a TokenLock to be mutably borrowed simultaneously, violating the pointer aliasing rules.

pub fn id(&self) -> SingletonTokenId<Tag>

Construct an SingletonTokenId that equates to self.

pub fn borrow(&self) -> SingletonTokenRef<'_, Tag, Variant>

Borrow self as SingletonTokenRef or UnsyncSingletonTokenRef of the same Sync-ness as Self.

SingletonTokenRef is truly zero-sized, so it's more efficient to store and pass than &SingletonToken.

pub fn borrow_mut(&mut self) -> SingletonTokenRefMut<'_, Tag, Variant>

Borrow self mutably as SingletonTokenRefMut or UnsyncSingletonTokenRefMut of the same Sync-ness as Self.

SingletonTokenRefMut is truly zero-sized, so it's more efficient to store and pass than &mut SingletonToken.

impl<Tag: ?Sized> SingletonToken<Tag, UnsyncVariant>

pub fn borrow_sync(&self) -> SingletonTokenRef<'_, Tag>

Borrow self: UnsyncSingletonToken as SingletonTokenRef.

pub fn borrow_sync_mut(&mut self) -> SingletonTokenRefMut<'_, Tag>

Borrow self: UnsyncSingletonToken mutably as SingletonTokenRefMut.

impl<Tag: ?Sized> SingletonToken<Tag>

pub fn borrow_unsync_mut(&mut self) -> UnsyncSingletonTokenRefMut<'_, Tag>

Borrow self: SingletonToken mutably as UnsyncSingletonTokenRefMut.

There is no borrow_unsync because that would allow UnsyncSingletonToken to be logically borrowed by multiple threads.

impl<Tag: ?Sized> SingletonToken<Tag>

pub const fn into_unsync(self) -> UnsyncSingletonToken<Tag>

Convert SingletonToken to the !Sync variant.

impl<Tag: ?Sized> SingletonToken<Tag, UnsyncVariant>

pub const fn into_sync(self) -> SingletonToken<Tag>

Convert UnsyncSingletonToken to the Sync variant.

Trait Implementations

impl<Tag: ?Sized, Variant: SingletonTokenVariant> Debug for SingletonToken<Tag, Variant>

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

Formats the value using the given formatter.

impl<Tag: ?Sized, Variant: SingletonTokenVariant> Eq for SingletonToken<Tag, Variant>

impl<Tag: ?Sized, Variant: SingletonTokenVariant> Hash for SingletonToken<Tag, Variant>

fn hash<H: Hasher>(&self, _: &mut H)

Feeds this value into the given Hasher.

pub fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl<Tag: ?Sized, Variant: SingletonTokenVariant> PartialEq<SingletonToken<Tag, Variant>> for SingletonToken<Tag, Variant>

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

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

#[must_use]pub fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<Tag: ?Sized, Variant: SingletonTokenVariant> Token<SingletonTokenId<Tag>> for SingletonToken<Tag, Variant>

fn eq_id(&self, _: &SingletonTokenId<Tag>) -> bool