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::{bindings, init::PinInit, pin_init, str::CStr, types::Opaque};
 10use core::marker::PhantomPinned;
 11use macros::pin_data;
 12
 13/// Creates a [`CondVar`] initialiser with the given name and a newly-created lock class.
 14#[macro_export]
 15macro_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]
 74pub 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)]
 86unsafe 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.
 90unsafe impl Sync for CondVar {}
 91
 92impl 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}