token_cell/
lib.rs

1#![deny(
2    clippy::missing_panics_doc,
3    clippy::missing_const_for_fn,
4    clippy::missing_safety_doc,
5    clippy::missing_errors_doc,
6    missing_docs
7)]
8
9//! This library provides an alternative to [`ghost-cell`](https://crates.io/crates/ghost-cell) which uses concrete types instead of lifetimes for branding.
10//!
11//! This allows a more convenient usage, where cells and tokens can be constructed independently, with the same compile-time guarantees as [`ghost-cell`](https://crates.io/crates/ghost-cell). The trade-off for this arguably more convenient usage and arguably easier to understand branding method is that tokens, while zero-sized if made correctly, must be guaranteed to be constructable only if no other instance exists.
12#![cfg_attr(not(feature = "std"), no_std)]
13pub use paste::paste;
14
15#[rustversion::since(1.90)]
16macro_rules! infallible_ok {
17    ($expr: expr) => {{
18        let Ok(r) = $expr;
19        r
20    }};
21}
22#[rustversion::before(1.90)]
23macro_rules! infallible_ok {
24    ($expr: expr) => {{
25        unsafe { $expr.unwrap_unchecked() }
26    }};
27}
28
29#[rustversion::before(1.81)]
30#[cfg(feature = "std")]
31mod std {
32    use crate::macros::SingletonUnavailable;
33    use crate::runtime_token_support::{IdMismatch, Identifier};
34    extern crate std;
35    impl<T: Identifier> std::error::Error for IdMismatch<T> {}
36    impl std::error::Error for SingletonUnavailable {}
37}
38#[rustversion::since(1.81)]
39mod std {
40    use crate::macros::SingletonUnavailable;
41    use crate::runtime_token_support::{IdMismatch, Identifier};
42    impl<T: Identifier> core::error::Error for IdMismatch<T> {}
43    impl core::error::Error for SingletonUnavailable {}
44}
45
46/// The basis for using `token_cell`
47pub mod prelude {
48    pub use crate::core::{
49        TokenCell, TokenCellTrait, TokenTrait, UnsafeTokenCellTrait, UnscopedToken,
50    };
51}
52pub use crate::macros::token;
53/// The core aspects of `token_cell`
54pub mod core;
55/// A traitified version of `ghost_cell`.
56///
57/// To use this, simply construct a [`TokenCell`](crate::prelude::TokenCell) using a [`GhostToken`](crate::ghost::GhostToken) obtained with the [`TokenTrait::with_token`](crate::prelude::TokenTrait::with_token) constructor.
58pub mod ghost;
59/// The macros to construct tokens.
60pub mod macros;
61/// Because monads are cool.
62pub mod monads;
63
64/// Support module for the [`runtime_token`] macro.
65pub mod runtime_token_support;
66
67runtime_token!(
68    /// The default runtime-checked token type.
69    ///
70    /// Because this token type is checked at runtime, it can make sense to have a global token type for your whole application.
71    ///
72    /// And because this runtime token is backed by a `u64`, it would take you 60 years continuously instantiating them at 10GHz
73    /// (which is unfeasible with existing hardware) before an overflow may cause multiple tokens to share the same runtime identifier;
74    /// so you can safely assume that this token type will never let you access a cell that you shouldn't be accessing.
75    pub RuntimeToken: u64
76);
token_cell/lib.rs

token_cell/
lib.rs
