rust/kernel/sync/condvar.rs

   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(&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`]: srctree/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     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
 123     /// Releases the lock and waits for a notification in uninterruptible mode.
 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
 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.
 137     ///
 138     /// Returns whether there is a signal pending.
 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 {
 141         self.wait_internal(bindings::TASK_INTERRUPTIBLE, guard);
 142         crate::current!().signal_pending()
 143     }
 144
 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 }