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::{
  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 };
  18 use core::ffi::{c_int, c_long};
  19 use core::marker::PhantomPinned;
  20 use core::ptr;
  21 use macros::pin_data;
  22
  23 /// Creates a [`CondVar`] initialiser with the given name and a newly-created lock class.
  24 #[macro_export]
  25 macro_rules! new_condvar {
  26     ($($name:literal)?) => {
  27         $crate::sync::CondVar::new($crate::optional_name!($($name)?), $crate::static_lock_class!())
  28     };
  29 }
  30 pub 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]
  84 pub 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)]
  98 unsafe 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.
 102 unsafe impl Sync for CondVar {}
 103
 104 impl 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`.
 226 pub 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 }