xref: /openbmc/linux/rust/kernel/sync/condvar.rs (revision 19096bce)
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 {
53 ///         e.value_changed.wait_uninterruptible(&mut guard);
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 ///
72 /// [`struct wait_queue_head`]: ../../../include/linux/wait.h
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.
94     #[allow(clippy::new_ret_no_self)]
new(name: &'static CStr, key: &'static LockClassKey) -> impl PinInit<Self>95     pub fn new(name: &'static CStr, key: &'static LockClassKey) -> impl PinInit<Self> {
96         pin_init!(Self {
97             _pin: PhantomPinned,
98             // SAFETY: `slot` is valid while the closure is called and both `name` and `key` have
99             // static lifetimes so they live indefinitely.
100             wait_list <- Opaque::ffi_init(|slot| unsafe {
101                 bindings::__init_waitqueue_head(slot, name.as_char_ptr(), key.as_ptr())
102             }),
103         })
104     }
105 
wait_internal<T: ?Sized, B: Backend>(&self, wait_state: u32, guard: &mut Guard<'_, T, B>)106     fn wait_internal<T: ?Sized, B: Backend>(&self, wait_state: u32, guard: &mut Guard<'_, T, B>) {
107         let wait = Opaque::<bindings::wait_queue_entry>::uninit();
108 
109         // SAFETY: `wait` points to valid memory.
110         unsafe { bindings::init_wait(wait.get()) };
111 
112         // SAFETY: Both `wait` and `wait_list` point to valid memory.
113         unsafe {
114             bindings::prepare_to_wait_exclusive(self.wait_list.get(), wait.get(), wait_state as _)
115         };
116 
117         // SAFETY: No arguments, switches to another thread.
118         guard.do_unlocked(|| unsafe { bindings::schedule() });
119 
120         // SAFETY: Both `wait` and `wait_list` point to valid memory.
121         unsafe { bindings::finish_wait(self.wait_list.get(), wait.get()) };
122     }
123 
124     /// Releases the lock and waits for a notification in interruptible mode.
125     ///
126     /// Atomically releases the given lock (whose ownership is proven by the guard) and puts the
127     /// thread to sleep, reacquiring the lock on wake up. It wakes up when notified by
128     /// [`CondVar::notify_one`] or [`CondVar::notify_all`], or when the thread receives a signal.
129     /// It may also wake up spuriously.
130     ///
131     /// Returns whether there is a signal pending.
132     #[must_use = "wait returns if a signal is pending, so the caller must check the return value"]
wait<T: ?Sized, B: Backend>(&self, guard: &mut Guard<'_, T, B>) -> bool133     pub fn wait<T: ?Sized, B: Backend>(&self, guard: &mut Guard<'_, T, B>) -> bool {
134         self.wait_internal(bindings::TASK_INTERRUPTIBLE, guard);
135         crate::current!().signal_pending()
136     }
137 
138     /// Releases the lock and waits for a notification in uninterruptible mode.
139     ///
140     /// Similar to [`CondVar::wait`], except that the wait is not interruptible. That is, the
141     /// thread won't wake up due to signals. It may, however, wake up supirously.
wait_uninterruptible<T: ?Sized, B: Backend>(&self, guard: &mut Guard<'_, T, B>)142     pub fn wait_uninterruptible<T: ?Sized, B: Backend>(&self, guard: &mut Guard<'_, T, B>) {
143         self.wait_internal(bindings::TASK_UNINTERRUPTIBLE, guard)
144     }
145 
146     /// Calls the kernel function to notify the appropriate number of threads with the given flags.
notify(&self, count: i32, flags: u32)147     fn notify(&self, count: i32, flags: u32) {
148         // SAFETY: `wait_list` points to valid memory.
149         unsafe {
150             bindings::__wake_up(
151                 self.wait_list.get(),
152                 bindings::TASK_NORMAL,
153                 count,
154                 flags as _,
155             )
156         };
157     }
158 
159     /// Wakes a single waiter up, if any.
160     ///
161     /// This is not 'sticky' in the sense that if no thread is waiting, the notification is lost
162     /// completely (as opposed to automatically waking up the next waiter).
notify_one(&self)163     pub fn notify_one(&self) {
164         self.notify(1, 0);
165     }
166 
167     /// Wakes all waiters up, if any.
168     ///
169     /// This is not 'sticky' in the sense that if no thread is waiting, the notification is lost
170     /// completely (as opposed to automatically waking up the next waiter).
notify_all(&self)171     pub fn notify_all(&self) {
172         self.notify(0, 0);
173     }
174 }
175