token-cell 2.1.1

A more convenient GhostCell
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108

use core::{cell::UnsafeCell, convert::Infallible};

use crate::core::TokenTrait;

/// The identifier for a [`GhostToken`]-based cell is its [`InvariantLifetime`]
#[derive(Clone, Copy)]
pub struct InvariantLifetime<'a>(core::marker::PhantomData<UnsafeCell<&'a ()>>);
impl<'a> InvariantLifetime<'a> {
    const fn new() -> Self {
        Self(core::marker::PhantomData)
    }
}

/// A lifetime based token, inspired by `ghost_cell`.
///
/// Correct usage, where cells are only unlocked by providing a mutable reference to the token they were constructed with, will compile.
/// ```rust
/// # use token_cell::{prelude::*, ghost::GhostToken};
/// GhostToken::with_token(|mut t1| {
///     let c1 = TokenCell::new(1, &t1);
///     GhostToken::with_token(|mut t2| {
///         let c2 = TokenCell::new(1, &t2);
///         println!("{}", *c2.borrow_mut(&mut t2));
///         println!("{}", *c1.borrow_mut(&mut t1));
///     })
///     .unwrap();
///     c1.borrow_mut(&mut t1);
/// })
/// .unwrap();
/// ```
///
/// But using the wrong token with any given cell will fail at compile time.
/// ```compile_fail
///  # use token_cell::{prelude::*, ghost::GhostToken};
///  GhostToken::with_token(|mut t1| {
///      let c1 = TokenCell::new(1, &t1);
///      GhostToken::with_token(|mut t2| {
///          println!("{}", *c1.borrow_mut(&mut t2));
///      })
///      .unwrap();
///      c1.borrow_mut(&mut t1);
///  })
///  .unwrap();
///  ```
/// ```compile_fail
/// # use token_cell::{prelude::*, ghost::GhostToken};
/// GhostToken::with_token(|mut t1| {
///     let c1 = TokenCell::new(1, &t1);
///     GhostToken::with_token(|mut t2| {
///         let c2 = TokenCell::new(1, &t2);
///         println!("{}", *c2.borrow_mut(&mut t1));
///         println!("{}", *c1.borrow_mut(&mut t1));
///     })
///     .unwrap();
///     c1.borrow_mut(&mut t1);
/// })
/// .unwrap();
/// ```
pub struct GhostToken<'brand>(InvariantLifetime<'brand>);
impl<'brand> TokenTrait for GhostToken<'brand> {
    type ConstructionError = ();
    type RunError = Infallible;
    type Identifier = InvariantLifetime<'brand>;
    type ComparisonError = Infallible;
    type Branded<'a> = GhostToken<'a>;
    fn new() -> Result<Self, Self::ConstructionError> {
        Err(())
    }
    /// ```rust
    /// use token_cell::{ghost::*, prelude::*};
    /// GhostToken::with_token(|mut t1| {
    ///     let c1 = TokenCell::new(1, &t1);
    ///     GhostToken::with_token(|mut t2| {
    ///         let c2 = TokenCell::new(1, &t2);
    ///         println!("{}", *c2.borrow_mut(&mut t2));
    ///         println!("{}", *c1.borrow_mut(&mut t1));
    ///     })
    ///     .unwrap();
    ///     c1.borrow_mut(&mut t1);
    /// })
    /// .unwrap();
    /// ```
    /// ```compile_fail
    /// use token_cell::{ghost::*, prelude::*};
    /// GhostToken::with_token(|mut t1| {
    ///     let c1 = TokenCell::new(1, &t1);
    ///     GhostToken::with_token(|mut t2| {
    ///         let c2 = TokenCell::new(1, &t2);
    ///         println!("{}", *c2.borrow_mut(&mut t2));
    ///         println!("{}", *c1.borrow_mut(&mut t2));
    ///     })
    ///     .unwrap();
    ///     c1.borrow_mut(&mut t1);
    /// })
    /// .unwrap();
    /// ```
    fn with_token<R, F: for<'a> FnOnce(Self::Branded<'a>) -> R>(f: F) -> Result<R, Self::RunError> {
        Ok(f(Self(InvariantLifetime::new())))
    }

    fn identifier(&self) -> InvariantLifetime<'brand> {
        self.0
    }

    fn compare(&self, _: &InvariantLifetime<'brand>) -> Result<(), Self::ComparisonError> {
        Ok(())
    }
}