static_init 1.0.3

Safe mutable static and non const static initialization, and code execution at program startup/exit.
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

#[cfg(not(feature = "spin_loop"))]
mod futex;

mod spin_wait;

#[cfg(not(feature = "spin_loop"))]
mod sync;

#[cfg(feature = "spin_loop")]
#[path = "phase_locker/sync_spinning.rs"]
mod sync;

pub(crate) use sync::Mutex;
pub(crate) use sync::{SyncPhaseGuard, SyncPhaseLocker, SyncReadPhaseGuard};

mod unsync;
pub(crate) use unsync::UnSyncPhaseLocker;
pub(crate) use unsync::{UnSyncPhaseGuard, UnSyncReadPhaseGuard};

use super::{Phase, Phased};

/// A phase guard ensure that the target object will
/// performed atomic phase transition
///
/// # Safety
///
/// The trait is unsafe because the implementation must fullfill the
/// following requirement described in the documentation of the functions
pub(crate) unsafe trait PhaseGuard<'a, T: ?Sized + 'a> {
    /// Set the phase at which will be the traget object
    /// when the phase guard will be dropped
    ///
    /// # Safety
    ///
    /// This function is unsafe because not providing a correct phase
    /// may lead to miss interpretation of the state of the target object
    /// which may result in unsound lazy
    fn set_phase(&mut self, p: Phase);
    /// Set the phase of the target object with release semantic if the
    /// PhaseGuard is Sync
    fn commit_phase(&mut self);
    /// Return the phase at which will be the object
    fn phase(&self) -> Phase;
    /// Execute the function f then:
    ///   - if execution of f does not panic change, call Self::set_phase(on_success)
    ///   - if execution of f panics: set the phase of the target object to on_panic and
    ///   release the lock.
    fn transition<R>(
        &mut self,
        f: impl FnOnce(&'a T) -> R,
        on_success: Phase,
        on_panic: Phase,
    ) -> R;
}

pub(crate) trait Mappable<T, V, U> {
    fn map<F: FnOnce(&T) -> &V>(self, f: F) -> U;
}

pub(crate) unsafe trait PhaseLocker<'a, T: 'a> {
    type ReadGuard: Phased;
    type WriteGuard: Phased + PhaseGuard<'a, T>;

    fn lock<FL: Fn(Phase) -> LockNature, FW: Fn(Phase) -> LockNature>(
        &'a self,
        value: &'a T,
        lock_nature: FL,
        on_wake_nature: FW,
        hint: Phase,
    ) -> LockResult<Self::ReadGuard, Self::WriteGuard>;
    fn lock_mut(&'a mut self, value: &'a T) -> Self::WriteGuard;
    fn try_lock<F: Fn(Phase) -> LockNature>(
        &'a self,
        value: &'a T,
        lock_nature: F,
        hint: Phase,
    ) -> Option<LockResult<Self::ReadGuard, Self::WriteGuard>>;
    fn phase(&self) -> Phase;
}

pub(crate) unsafe trait MutPhaseLocker {
    fn get_phase_unique(&mut self) -> Phase;
    fn set_phase(&mut self, p: Phase);

    fn transition<R>(&mut self, f: impl FnOnce() -> R, on_success: Phase, on_panic: Phase) -> R;
}

/// Nature of the lock requested
#[derive(Copy, Clone, Debug, Eq, PartialEq)]
pub enum LockNature {
    Read,
    Write,
    None,
}
/// Result of a Phased locking
pub enum LockResult<R, W> {
    Read(R),
    Write(W),
    None(Phase),
}

#[cfg(all(feature = "lock_statistics", not(feature = "spin_loop")))]
pub use sync::LockStatistics;