projects/linux·blob uaccess-cleanups · refs

258 lines · 9.4 KiB

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