Commit | Line | Data |
---|---|---|
19096bce WAF |
1 | // SPDX-License-Identifier: GPL-2.0 |
2 | ||
3 | //! A condition variable. | |
4 | //! | |
5 | //! This module allows Rust code to use the kernel's [`struct wait_queue_head`] as a condition | |
6 | //! variable. | |
7 | ||
8 | use super::{lock::Backend, lock::Guard, LockClassKey}; | |
9 | use crate::{bindings, init::PinInit, pin_init, str::CStr, types::Opaque}; | |
10 | use core::marker::PhantomPinned; | |
11 | use macros::pin_data; | |
12 | ||
13 | /// Creates a [`CondVar`] initialiser with the given name and a newly-created lock class. | |
14 | #[macro_export] | |
15 | macro_rules! new_condvar { | |
16 | ($($name:literal)?) => { | |
17 | $crate::sync::CondVar::new($crate::optional_name!($($name)?), $crate::static_lock_class!()) | |
18 | }; | |
19 | } | |
20 | ||
21 | /// A conditional variable. | |
22 | /// | |
23 | /// Exposes the kernel's [`struct wait_queue_head`] as a condition variable. It allows the caller to | |
24 | /// atomically release the given lock and go to sleep. It reacquires the lock when it wakes up. And | |
25 | /// it wakes up when notified by another thread (via [`CondVar::notify_one`] or | |
26 | /// [`CondVar::notify_all`]) or because the thread received a signal. It may also wake up | |
27 | /// spuriously. | |
28 | /// | |
29 | /// Instances of [`CondVar`] need a lock class and to be pinned. The recommended way to create such | |
30 | /// instances is with the [`pin_init`](crate::pin_init) and [`new_condvar`] macros. | |
31 | /// | |
32 | /// # Examples | |
33 | /// | |
34 | /// The following is an example of using a condvar with a mutex: | |
35 | /// | |
36 | /// ``` | |
37 | /// use kernel::sync::{CondVar, Mutex}; | |
38 | /// use kernel::{new_condvar, new_mutex}; | |
39 | /// | |
40 | /// #[pin_data] | |
41 | /// pub struct Example { | |
42 | /// #[pin] | |
43 | /// value: Mutex<u32>, | |
44 | /// | |
45 | /// #[pin] | |
46 | /// value_changed: CondVar, | |
47 | /// } | |
48 | /// | |
49 | /// /// Waits for `e.value` to become `v`. | |
50 | /// fn wait_for_value(e: &Example, v: u32) { | |
51 | /// let mut guard = e.value.lock(); | |
52 | /// while *guard != v { | |
0a7f5ba7 | 53 | /// e.value_changed.wait(&mut guard); |
19096bce WAF |
54 | /// } |
55 | /// } | |
56 | /// | |
57 | /// /// Increments `e.value` and notifies all potential waiters. | |
58 | /// fn increment(e: &Example) { | |
59 | /// *e.value.lock() += 1; | |
60 | /// e.value_changed.notify_all(); | |
61 | /// } | |
62 | /// | |
63 | /// /// Allocates a new boxed `Example`. | |
64 | /// fn new_example() -> Result<Pin<Box<Example>>> { | |
65 | /// Box::pin_init(pin_init!(Example { | |
66 | /// value <- new_mutex!(0), | |
67 | /// value_changed <- new_condvar!(), | |
68 | /// })) | |
69 | /// } | |
70 | /// ``` | |
71 | /// | |
bc2e7d5c | 72 | /// [`struct wait_queue_head`]: srctree/include/linux/wait.h |
19096bce WAF |
73 | #[pin_data] |
74 | pub struct CondVar { | |
75 | #[pin] | |
76 | pub(crate) wait_list: Opaque<bindings::wait_queue_head>, | |
77 | ||
78 | /// A condvar needs to be pinned because it contains a [`struct list_head`] that is | |
79 | /// self-referential, so it cannot be safely moved once it is initialised. | |
80 | #[pin] | |
81 | _pin: PhantomPinned, | |
82 | } | |
83 | ||
84 | // SAFETY: `CondVar` only uses a `struct wait_queue_head`, which is safe to use on any thread. | |
85 | #[allow(clippy::non_send_fields_in_send_ty)] | |
86 | unsafe impl Send for CondVar {} | |
87 | ||
88 | // SAFETY: `CondVar` only uses a `struct wait_queue_head`, which is safe to use on multiple threads | |
89 | // concurrently. | |
90 | unsafe impl Sync for CondVar {} | |
91 | ||
92 | impl CondVar { | |
93 | /// Constructs a new condvar initialiser. | |
19096bce WAF |
94 | pub fn new(name: &'static CStr, key: &'static LockClassKey) -> impl PinInit<Self> { |
95 | pin_init!(Self { | |
96 | _pin: PhantomPinned, | |
97 | // SAFETY: `slot` is valid while the closure is called and both `name` and `key` have | |
98 | // static lifetimes so they live indefinitely. | |
99 | wait_list <- Opaque::ffi_init(|slot| unsafe { | |
100 | bindings::__init_waitqueue_head(slot, name.as_char_ptr(), key.as_ptr()) | |
101 | }), | |
102 | }) | |
103 | } | |
104 | ||
105 | fn wait_internal<T: ?Sized, B: Backend>(&self, wait_state: u32, guard: &mut Guard<'_, T, B>) { | |
106 | let wait = Opaque::<bindings::wait_queue_entry>::uninit(); | |
107 | ||
108 | // SAFETY: `wait` points to valid memory. | |
109 | unsafe { bindings::init_wait(wait.get()) }; | |
110 | ||
111 | // SAFETY: Both `wait` and `wait_list` point to valid memory. | |
112 | unsafe { | |
113 | bindings::prepare_to_wait_exclusive(self.wait_list.get(), wait.get(), wait_state as _) | |
114 | }; | |
115 | ||
116 | // SAFETY: No arguments, switches to another thread. | |
117 | guard.do_unlocked(|| unsafe { bindings::schedule() }); | |
118 | ||
119 | // SAFETY: Both `wait` and `wait_list` point to valid memory. | |
120 | unsafe { bindings::finish_wait(self.wait_list.get(), wait.get()) }; | |
121 | } | |
122 | ||
0a7f5ba7 | 123 | /// Releases the lock and waits for a notification in uninterruptible mode. |
19096bce WAF |
124 | /// |
125 | /// Atomically releases the given lock (whose ownership is proven by the guard) and puts the | |
126 | /// thread to sleep, reacquiring the lock on wake up. It wakes up when notified by | |
0a7f5ba7 BF |
127 | /// [`CondVar::notify_one`] or [`CondVar::notify_all`]. Note that it may also wake up |
128 | /// spuriously. | |
129 | pub fn wait<T: ?Sized, B: Backend>(&self, guard: &mut Guard<'_, T, B>) { | |
130 | self.wait_internal(bindings::TASK_UNINTERRUPTIBLE, guard); | |
131 | } | |
132 | ||
133 | /// Releases the lock and waits for a notification in interruptible mode. | |
134 | /// | |
135 | /// Similar to [`CondVar::wait`], except that the wait is interruptible. That is, the thread may | |
136 | /// wake up due to signals. It may also wake up spuriously. | |
19096bce WAF |
137 | /// |
138 | /// Returns whether there is a signal pending. | |
0a7f5ba7 BF |
139 | #[must_use = "wait_interruptible returns if a signal is pending, so the caller must check the return value"] |
140 | pub fn wait_interruptible<T: ?Sized, B: Backend>(&self, guard: &mut Guard<'_, T, B>) -> bool { | |
19096bce WAF |
141 | self.wait_internal(bindings::TASK_INTERRUPTIBLE, guard); |
142 | crate::current!().signal_pending() | |
143 | } | |
144 | ||
19096bce WAF |
145 | /// Calls the kernel function to notify the appropriate number of threads with the given flags. |
146 | fn notify(&self, count: i32, flags: u32) { | |
147 | // SAFETY: `wait_list` points to valid memory. | |
148 | unsafe { | |
149 | bindings::__wake_up( | |
150 | self.wait_list.get(), | |
151 | bindings::TASK_NORMAL, | |
152 | count, | |
153 | flags as _, | |
154 | ) | |
155 | }; | |
156 | } | |
157 | ||
158 | /// Wakes a single waiter up, if any. | |
159 | /// | |
160 | /// This is not 'sticky' in the sense that if no thread is waiting, the notification is lost | |
161 | /// completely (as opposed to automatically waking up the next waiter). | |
162 | pub fn notify_one(&self) { | |
163 | self.notify(1, 0); | |
164 | } | |
165 | ||
166 | /// Wakes all waiters up, if any. | |
167 | /// | |
168 | /// This is not 'sticky' in the sense that if no thread is waiting, the notification is lost | |
169 | /// completely (as opposed to automatically waking up the next waiter). | |
170 | pub fn notify_all(&self) { | |
171 | self.notify(0, 0); | |
172 | } | |
173 | } |