surelock 0.1.0

Deadlock-free locks for Rust with compile time guarantees, incremental locks, and atomic lock sets.
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

#![allow(unsafe_code)]
//! Transferable token redeemable for a [`KeyHandle`].
//!
//! A [`KeyVoucher`] is issued by a [`Locksmith`](crate::locksmith::Locksmith)
//! and can be sent (`Send`) to another thread or core. On arrival,
//! call [`redeem`](KeyVoucher::redeem) to obtain a
//! [`KeyHandle`] for that execution context.
//!
//! `Send`, `!Clone`, `!Copy` -- each voucher is a unique, single-use token.
//!
//! # Examples
//!
//! ```rust
//! use surelock::locksmith::Locksmith;
//!
//! let smith = Locksmith::new(2).unwrap();
//! let voucher = smith.issue().unwrap();
//!
//! // Send voucher to another thread...
//! let handle = std::thread::spawn(move || {
//!     let mut key_handle = voucher.redeem().unwrap();
//!     key_handle.scope(|key| {
//!         // lock things...
//!     });
//! });
//! handle.join().unwrap();
//! ```

use crate::key_handle::KeyHandle;

/// Transferable token redeemable for a [`KeyHandle`].
///
/// Issued by [`Locksmith::issue`](crate::locksmith::Locksmith::issue).
/// `Send` (can cross thread/core boundaries), `!Clone`, `!Copy`.
///
/// On `std`, [`redeem`](KeyVoucher::redeem) checks the
/// `thread_local!` flag and returns `Option<KeyHandle>`. On `no_std`,
/// `redeem` is infallible (returns `KeyHandle` directly) -- per-context
/// uniqueness is a setup discipline.
#[allow(missing_copy_implementations)] // Intentionally !Copy -- one-use token
pub struct KeyVoucher {
    // Private field prevents external construction.
    // No PhantomData<*const ()> -- KeyVoucher IS Send.
    _private: (),
}

// Explicitly implement Send. KeyVoucher is designed to cross
// thread/core boundaries.
unsafe impl Send for KeyVoucher {}

impl KeyVoucher {
    /// Create a voucher. Only callable within the crate --
    /// external users get vouchers from
    /// [`Locksmith::issue`](crate::locksmith::Locksmith::issue).
    pub(crate) const fn new_internal() -> Self {
        Self { _private: () }
    }

    /// Redeem this voucher for a [`KeyHandle`] on the current thread.
    ///
    /// On `std`: returns `Some(KeyHandle)` if no handle is already
    /// claimed on this thread, `None` otherwise. Uses the same
    /// `thread_local!` mechanism as
    /// [`KeyHandle::try_claim`](crate::key_handle::KeyHandle::try_claim).
    ///
    /// On `no_std`: always returns `KeyHandle` (infallible). Per-context
    /// uniqueness is a setup discipline -- the
    /// [`Locksmith`](crate::locksmith::Locksmith)'s limit prevents
    /// over-issuance, but two vouchers redeemed on the same core
    /// are not detected.
    #[must_use]
    #[cfg(feature = "std")]
    pub fn redeem(self) -> Option<KeyHandle> {
        KeyHandle::try_claim()
    }

    /// Redeem this voucher for a [`KeyHandle`] on the current
    /// execution context.
    ///
    /// On `no_std`, this is infallible -- per-context uniqueness is
    /// a setup discipline.
    ///
    /// # Panics
    ///
    /// Panics if `KeyHandle::try_claim` returns `None`. This is
    /// unreachable on `no_std` (where `try_claim` always succeeds)
    /// but is retained as a defensive assertion.
    #[must_use]
    #[allow(clippy::expect_used)]
    #[cfg(not(feature = "std"))]
    pub fn redeem(self) -> KeyHandle {
        KeyHandle::try_claim().expect("KeyHandle::try_claim always succeeds on no_std")
    }
}

impl core::fmt::Debug for KeyVoucher {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("KeyVoucher").finish_non_exhaustive()
    }
}