Loading...
Note: File does not exist in v6.2.
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
8use super::{lock::Backend, lock::Guard, LockClassKey};
9use crate::{
10 bindings,
11 init::PinInit,
12 pin_init,
13 str::CStr,
14 task::{MAX_SCHEDULE_TIMEOUT, TASK_INTERRUPTIBLE, TASK_NORMAL, TASK_UNINTERRUPTIBLE},
15 time::Jiffies,
16 types::Opaque,
17};
18use core::ffi::{c_int, c_long};
19use core::marker::PhantomPinned;
20use core::ptr;
21use macros::pin_data;
22
23/// Creates a [`CondVar`] initialiser with the given name and a newly-created lock class.
24#[macro_export]
25macro_rules! new_condvar {
26 ($($name:literal)?) => {
27 $crate::sync::CondVar::new($crate::optional_name!($($name)?), $crate::static_lock_class!())
28 };
29}
30pub use new_condvar;
31
32/// A conditional variable.
33///
34/// Exposes the kernel's [`struct wait_queue_head`] as a condition variable. It allows the caller to
35/// atomically release the given lock and go to sleep. It reacquires the lock when it wakes up. And
36/// it wakes up when notified by another thread (via [`CondVar::notify_one`] or
37/// [`CondVar::notify_all`]) or because the thread received a signal. It may also wake up
38/// spuriously.
39///
40/// Instances of [`CondVar`] need a lock class and to be pinned. The recommended way to create such
41/// instances is with the [`pin_init`](crate::pin_init) and [`new_condvar`] macros.
42///
43/// # Examples
44///
45/// The following is an example of using a condvar with a mutex:
46///
47/// ```
48/// use kernel::sync::{new_condvar, new_mutex, CondVar, Mutex};
49///
50/// #[pin_data]
51/// pub struct Example {
52/// #[pin]
53/// value: Mutex<u32>,
54///
55/// #[pin]
56/// value_changed: CondVar,
57/// }
58///
59/// /// Waits for `e.value` to become `v`.
60/// fn wait_for_value(e: &Example, v: u32) {
61/// let mut guard = e.value.lock();
62/// while *guard != v {
63/// e.value_changed.wait(&mut guard);
64/// }
65/// }
66///
67/// /// Increments `e.value` and notifies all potential waiters.
68/// fn increment(e: &Example) {
69/// *e.value.lock() += 1;
70/// e.value_changed.notify_all();
71/// }
72///
73/// /// Allocates a new boxed `Example`.
74/// fn new_example() -> Result<Pin<Box<Example>>> {
75/// Box::pin_init(pin_init!(Example {
76/// value <- new_mutex!(0),
77/// value_changed <- new_condvar!(),
78/// }))
79/// }
80/// ```
81///
82/// [`struct wait_queue_head`]: srctree/include/linux/wait.h
83#[pin_data]
84pub struct CondVar {
85 #[pin]
86 pub(crate) wait_queue_head: Opaque<bindings::wait_queue_head>,
87
88 /// A condvar needs to be pinned because it contains a [`struct list_head`] that is
89 /// self-referential, so it cannot be safely moved once it is initialised.
90 ///
91 /// [`struct list_head`]: srctree/include/linux/types.h
92 #[pin]
93 _pin: PhantomPinned,
94}
95
96// SAFETY: `CondVar` only uses a `struct wait_queue_head`, which is safe to use on any thread.
97#[allow(clippy::non_send_fields_in_send_ty)]
98unsafe impl Send for CondVar {}
99
100// SAFETY: `CondVar` only uses a `struct wait_queue_head`, which is safe to use on multiple threads
101// concurrently.
102unsafe impl Sync for CondVar {}
103
104impl CondVar {
105 /// Constructs a new condvar initialiser.
106 pub fn new(name: &'static CStr, key: &'static LockClassKey) -> impl PinInit<Self> {
107 pin_init!(Self {
108 _pin: PhantomPinned,
109 // SAFETY: `slot` is valid while the closure is called and both `name` and `key` have
110 // static lifetimes so they live indefinitely.
111 wait_queue_head <- Opaque::ffi_init(|slot| unsafe {
112 bindings::__init_waitqueue_head(slot, name.as_char_ptr(), key.as_ptr())
113 }),
114 })
115 }
116
117 fn wait_internal<T: ?Sized, B: Backend>(
118 &self,
119 wait_state: c_int,
120 guard: &mut Guard<'_, T, B>,
121 timeout_in_jiffies: c_long,
122 ) -> c_long {
123 let wait = Opaque::<bindings::wait_queue_entry>::uninit();
124
125 // SAFETY: `wait` points to valid memory.
126 unsafe { bindings::init_wait(wait.get()) };
127
128 // SAFETY: Both `wait` and `wait_queue_head` point to valid memory.
129 unsafe {
130 bindings::prepare_to_wait_exclusive(self.wait_queue_head.get(), wait.get(), wait_state)
131 };
132
133 // SAFETY: Switches to another thread. The timeout can be any number.
134 let ret = guard.do_unlocked(|| unsafe { bindings::schedule_timeout(timeout_in_jiffies) });
135
136 // SAFETY: Both `wait` and `wait_queue_head` point to valid memory.
137 unsafe { bindings::finish_wait(self.wait_queue_head.get(), wait.get()) };
138
139 ret
140 }
141
142 /// Releases the lock and waits for a notification in uninterruptible mode.
143 ///
144 /// Atomically releases the given lock (whose ownership is proven by the guard) and puts the
145 /// thread to sleep, reacquiring the lock on wake up. It wakes up when notified by
146 /// [`CondVar::notify_one`] or [`CondVar::notify_all`]. Note that it may also wake up
147 /// spuriously.
148 pub fn wait<T: ?Sized, B: Backend>(&self, guard: &mut Guard<'_, T, B>) {
149 self.wait_internal(TASK_UNINTERRUPTIBLE, guard, MAX_SCHEDULE_TIMEOUT);
150 }
151
152 /// Releases the lock and waits for a notification in interruptible mode.
153 ///
154 /// Similar to [`CondVar::wait`], except that the wait is interruptible. That is, the thread may
155 /// wake up due to signals. It may also wake up spuriously.
156 ///
157 /// Returns whether there is a signal pending.
158 #[must_use = "wait_interruptible returns if a signal is pending, so the caller must check the return value"]
159 pub fn wait_interruptible<T: ?Sized, B: Backend>(&self, guard: &mut Guard<'_, T, B>) -> bool {
160 self.wait_internal(TASK_INTERRUPTIBLE, guard, MAX_SCHEDULE_TIMEOUT);
161 crate::current!().signal_pending()
162 }
163
164 /// Releases the lock and waits for a notification in interruptible mode.
165 ///
166 /// Atomically releases the given lock (whose ownership is proven by the guard) and puts the
167 /// thread to sleep. It wakes up when notified by [`CondVar::notify_one`] or
168 /// [`CondVar::notify_all`], or when a timeout occurs, or when the thread receives a signal.
169 #[must_use = "wait_interruptible_timeout returns if a signal is pending, so the caller must check the return value"]
170 pub fn wait_interruptible_timeout<T: ?Sized, B: Backend>(
171 &self,
172 guard: &mut Guard<'_, T, B>,
173 jiffies: Jiffies,
174 ) -> CondVarTimeoutResult {
175 let jiffies = jiffies.try_into().unwrap_or(MAX_SCHEDULE_TIMEOUT);
176 let res = self.wait_internal(TASK_INTERRUPTIBLE, guard, jiffies);
177
178 match (res as Jiffies, crate::current!().signal_pending()) {
179 (jiffies, true) => CondVarTimeoutResult::Signal { jiffies },
180 (0, false) => CondVarTimeoutResult::Timeout,
181 (jiffies, false) => CondVarTimeoutResult::Woken { jiffies },
182 }
183 }
184
185 /// Calls the kernel function to notify the appropriate number of threads.
186 fn notify(&self, count: c_int) {
187 // SAFETY: `wait_queue_head` points to valid memory.
188 unsafe {
189 bindings::__wake_up(
190 self.wait_queue_head.get(),
191 TASK_NORMAL,
192 count,
193 ptr::null_mut(),
194 )
195 };
196 }
197
198 /// Calls the kernel function to notify one thread synchronously.
199 ///
200 /// This method behaves like `notify_one`, except that it hints to the scheduler that the
201 /// current thread is about to go to sleep, so it should schedule the target thread on the same
202 /// CPU.
203 pub fn notify_sync(&self) {
204 // SAFETY: `wait_queue_head` points to valid memory.
205 unsafe { bindings::__wake_up_sync(self.wait_queue_head.get(), TASK_NORMAL) };
206 }
207
208 /// Wakes a single waiter up, if any.
209 ///
210 /// This is not 'sticky' in the sense that if no thread is waiting, the notification is lost
211 /// completely (as opposed to automatically waking up the next waiter).
212 pub fn notify_one(&self) {
213 self.notify(1);
214 }
215
216 /// Wakes all waiters up, if any.
217 ///
218 /// This is not 'sticky' in the sense that if no thread is waiting, the notification is lost
219 /// completely (as opposed to automatically waking up the next waiter).
220 pub fn notify_all(&self) {
221 self.notify(0);
222 }
223}
224
225/// The return type of `wait_timeout`.
226pub enum CondVarTimeoutResult {
227 /// The timeout was reached.
228 Timeout,
229 /// Somebody woke us up.
230 Woken {
231 /// Remaining sleep duration.
232 jiffies: Jiffies,
233 },
234 /// A signal occurred.
235 Signal {
236 /// Remaining sleep duration.
237 jiffies: Jiffies,
238 },
239}