kio 0.5.4

Easy async
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
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

use std::{
	fmt,
	ops::{Deref, DerefMut},
	// std, not `crate::sync`: [`WeakLock`] needs `Arc::downgrade`, which loom's Arc
	// doesn't have. Loom still models the `Mutex` inside, which is the part that
	// orders every handle against every other.
	sync::{Arc, Weak},
};

use crate::sync::{Mutex, MutexGuard};

/// A cloneable mutex wrapper backed by `Arc<Mutex<T>>`.
///
/// Every kio channel keeps its state in one of these, with its [`WaiterList`]s inside,
/// so a state change and the wake it owes are decided under a single lock. [`Fan`] can
/// hand out a [`Waker`](std::task::Waker) for one of those lists. See
/// [`Fan::project`](crate::Fan::project).
///
/// Poisoning is not part of the contract: a panic while the lock is held poisons it, and
/// every method here panics in turn rather than handing back a `Result`.
///
/// [`WaiterList`]: crate::WaiterList
/// [`Fan`]: crate::Fan
pub struct Lock<T> {
	inner: Arc<Mutex<T>>,
}

impl<T> Lock<T> {
	/// Wrap a value.
	pub fn new(value: T) -> Self {
		Self {
			inner: Arc::new(Mutex::new(value)),
		}
	}

	/// Lock the state, blocking until it is free. Panics if the lock was poisoned.
	pub fn lock(&self) -> LockGuard<'_, T> {
		LockGuard {
			inner: self.inner.lock().expect("mutex poisoned"),
		}
	}

	/// Whether both handles point at the same state.
	pub fn is_clone(&self, other: &Self) -> bool {
		Arc::ptr_eq(&self.inner, &other.inner)
	}

	/// Create a handle that doesn't own the value, so it can be stored inside the
	/// value itself without leaking the allocation.
	pub fn downgrade(&self) -> WeakLock<T> {
		WeakLock {
			inner: Arc::downgrade(&self.inner),
		}
	}
}

/// A [`Lock`] that doesn't own its value, backed by `Weak<Mutex<T>>`.
pub struct WeakLock<T> {
	inner: Weak<Mutex<T>>,
}

impl<T> WeakLock<T> {
	/// A handle that never upgrades, for a placeholder before a value exists.
	pub fn new() -> Self {
		Self { inner: Weak::new() }
	}

	/// Recover the owning [`Lock`], or `None` once the value has been dropped.
	pub fn upgrade(&self) -> Option<Lock<T>> {
		Some(Lock {
			inner: self.inner.upgrade()?,
		})
	}
}

impl<T> Clone for WeakLock<T> {
	fn clone(&self) -> Self {
		Self {
			inner: self.inner.clone(),
		}
	}
}

impl<T> fmt::Debug for WeakLock<T> {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
		f.debug_tuple("WeakLock").finish()
	}
}

impl<T> Clone for Lock<T> {
	fn clone(&self) -> Self {
		Self {
			inner: self.inner.clone(),
		}
	}
}

impl<T: fmt::Debug> fmt::Debug for Lock<T> {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
		match self.inner.try_lock() {
			Ok(guard) => f.debug_tuple("Lock").field(&*guard).finish(),
			Err(_) => f.debug_tuple("Lock").field(&"<locked>").finish(),
		}
	}
}

/// A guard providing access to the locked value. Releases the lock on drop.
pub struct LockGuard<'a, T> {
	inner: MutexGuard<'a, T>,
}

impl<T: fmt::Debug> fmt::Debug for LockGuard<'_, T> {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
		f.debug_tuple("LockGuard").field(&*self.inner).finish()
	}
}

impl<T> Deref for LockGuard<'_, T> {
	type Target = T;

	fn deref(&self) -> &Self::Target {
		&self.inner
	}
}

impl<T> DerefMut for LockGuard<'_, T> {
	fn deref_mut(&mut self) -> &mut Self::Target {
		&mut self.inner
	}
}

impl<T> Default for WeakLock<T> {
	fn default() -> Self {
		Self::new()
	}
}