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
  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}