239 lines · rust
1// SPDX-License-Identifier: GPL-2.02 3//! A condition variable.4//!5//! This module allows Rust code to use the kernel's [`struct wait_queue_head`] as a condition6//! variable.7 8use super::{lock::Backend, lock::Guard, LockClassKey};9use crate::{10 init::PinInit,11 pin_init,12 str::CStr,13 task::{MAX_SCHEDULE_TIMEOUT, TASK_INTERRUPTIBLE, TASK_NORMAL, TASK_UNINTERRUPTIBLE},14 time::Jiffies,15 types::Opaque,16};17use core::ffi::{c_int, c_long};18use core::marker::PhantomPinned;19use core::ptr;20use macros::pin_data;21 22/// Creates a [`CondVar`] initialiser with the given name and a newly-created lock class.23#[macro_export]24macro_rules! new_condvar {25 ($($name:literal)?) => {26 $crate::sync::CondVar::new($crate::optional_name!($($name)?), $crate::static_lock_class!())27 };28}29pub use new_condvar;30 31/// A conditional variable.32///33/// Exposes the kernel's [`struct wait_queue_head`] as a condition variable. It allows the caller to34/// atomically release the given lock and go to sleep. It reacquires the lock when it wakes up. And35/// it wakes up when notified by another thread (via [`CondVar::notify_one`] or36/// [`CondVar::notify_all`]) or because the thread received a signal. It may also wake up37/// spuriously.38///39/// Instances of [`CondVar`] need a lock class and to be pinned. The recommended way to create such40/// instances is with the [`pin_init`](crate::pin_init) and [`new_condvar`] macros.41///42/// # Examples43///44/// The following is an example of using a condvar with a mutex:45///46/// ```47/// use kernel::sync::{new_condvar, new_mutex, CondVar, Mutex};48///49/// #[pin_data]50/// pub struct Example {51/// #[pin]52/// value: Mutex<u32>,53///54/// #[pin]55/// value_changed: CondVar,56/// }57///58/// /// Waits for `e.value` to become `v`.59/// fn wait_for_value(e: &Example, v: u32) {60/// let mut guard = e.value.lock();61/// while *guard != v {62/// e.value_changed.wait(&mut guard);63/// }64/// }65///66/// /// Increments `e.value` and notifies all potential waiters.67/// fn increment(e: &Example) {68/// *e.value.lock() += 1;69/// e.value_changed.notify_all();70/// }71///72/// /// Allocates a new boxed `Example`.73/// fn new_example() -> Result<Pin<Box<Example>>> {74/// Box::pin_init(pin_init!(Example {75/// value <- new_mutex!(0),76/// value_changed <- new_condvar!(),77/// }), GFP_KERNEL)78/// }79/// ```80///81/// [`struct wait_queue_head`]: srctree/include/linux/wait.h82#[pin_data]83pub struct CondVar {84 #[pin]85 pub(crate) wait_queue_head: Opaque<bindings::wait_queue_head>,86 87 /// A condvar needs to be pinned because it contains a [`struct list_head`] that is88 /// self-referential, so it cannot be safely moved once it is initialised.89 ///90 /// [`struct list_head`]: srctree/include/linux/types.h91 #[pin]92 _pin: PhantomPinned,93}94 95// SAFETY: `CondVar` only uses a `struct wait_queue_head`, which is safe to use on any thread.96#[allow(clippy::non_send_fields_in_send_ty)]97unsafe impl Send for CondVar {}98 99// SAFETY: `CondVar` only uses a `struct wait_queue_head`, which is safe to use on multiple threads100// concurrently.101unsafe impl Sync for CondVar {}102 103impl CondVar {104 /// Constructs a new condvar initialiser.105 pub fn new(name: &'static CStr, key: &'static LockClassKey) -> impl PinInit<Self> {106 pin_init!(Self {107 _pin: PhantomPinned,108 // SAFETY: `slot` is valid while the closure is called and both `name` and `key` have109 // static lifetimes so they live indefinitely.110 wait_queue_head <- Opaque::ffi_init(|slot| unsafe {111 bindings::__init_waitqueue_head(slot, name.as_char_ptr(), key.as_ptr())112 }),113 })114 }115 116 fn wait_internal<T: ?Sized, B: Backend>(117 &self,118 wait_state: c_int,119 guard: &mut Guard<'_, T, B>,120 timeout_in_jiffies: c_long,121 ) -> c_long {122 let wait = Opaque::<bindings::wait_queue_entry>::uninit();123 124 // SAFETY: `wait` points to valid memory.125 unsafe { bindings::init_wait(wait.get()) };126 127 // SAFETY: Both `wait` and `wait_queue_head` point to valid memory.128 unsafe {129 bindings::prepare_to_wait_exclusive(self.wait_queue_head.get(), wait.get(), wait_state)130 };131 132 // SAFETY: Switches to another thread. The timeout can be any number.133 let ret = guard.do_unlocked(|| unsafe { bindings::schedule_timeout(timeout_in_jiffies) });134 135 // SAFETY: Both `wait` and `wait_queue_head` point to valid memory.136 unsafe { bindings::finish_wait(self.wait_queue_head.get(), wait.get()) };137 138 ret139 }140 141 /// Releases the lock and waits for a notification in uninterruptible mode.142 ///143 /// Atomically releases the given lock (whose ownership is proven by the guard) and puts the144 /// thread to sleep, reacquiring the lock on wake up. It wakes up when notified by145 /// [`CondVar::notify_one`] or [`CondVar::notify_all`]. Note that it may also wake up146 /// spuriously.147 pub fn wait<T: ?Sized, B: Backend>(&self, guard: &mut Guard<'_, T, B>) {148 self.wait_internal(TASK_UNINTERRUPTIBLE, guard, MAX_SCHEDULE_TIMEOUT);149 }150 151 /// Releases the lock and waits for a notification in interruptible mode.152 ///153 /// Similar to [`CondVar::wait`], except that the wait is interruptible. That is, the thread may154 /// wake up due to signals. It may also wake up spuriously.155 ///156 /// Returns whether there is a signal pending.157 #[must_use = "wait_interruptible returns if a signal is pending, so the caller must check the return value"]158 pub fn wait_interruptible<T: ?Sized, B: Backend>(&self, guard: &mut Guard<'_, T, B>) -> bool {159 self.wait_internal(TASK_INTERRUPTIBLE, guard, MAX_SCHEDULE_TIMEOUT);160 crate::current!().signal_pending()161 }162 163 /// Releases the lock and waits for a notification in interruptible mode.164 ///165 /// Atomically releases the given lock (whose ownership is proven by the guard) and puts the166 /// thread to sleep. It wakes up when notified by [`CondVar::notify_one`] or167 /// [`CondVar::notify_all`], or when a timeout occurs, or when the thread receives a signal.168 #[must_use = "wait_interruptible_timeout returns if a signal is pending, so the caller must check the return value"]169 pub fn wait_interruptible_timeout<T: ?Sized, B: Backend>(170 &self,171 guard: &mut Guard<'_, T, B>,172 jiffies: Jiffies,173 ) -> CondVarTimeoutResult {174 let jiffies = jiffies.try_into().unwrap_or(MAX_SCHEDULE_TIMEOUT);175 let res = self.wait_internal(TASK_INTERRUPTIBLE, guard, jiffies);176 177 match (res as Jiffies, crate::current!().signal_pending()) {178 (jiffies, true) => CondVarTimeoutResult::Signal { jiffies },179 (0, false) => CondVarTimeoutResult::Timeout,180 (jiffies, false) => CondVarTimeoutResult::Woken { jiffies },181 }182 }183 184 /// Calls the kernel function to notify the appropriate number of threads.185 fn notify(&self, count: c_int) {186 // SAFETY: `wait_queue_head` points to valid memory.187 unsafe {188 bindings::__wake_up(189 self.wait_queue_head.get(),190 TASK_NORMAL,191 count,192 ptr::null_mut(),193 )194 };195 }196 197 /// Calls the kernel function to notify one thread synchronously.198 ///199 /// This method behaves like `notify_one`, except that it hints to the scheduler that the200 /// current thread is about to go to sleep, so it should schedule the target thread on the same201 /// CPU.202 pub fn notify_sync(&self) {203 // SAFETY: `wait_queue_head` points to valid memory.204 unsafe { bindings::__wake_up_sync(self.wait_queue_head.get(), TASK_NORMAL) };205 }206 207 /// Wakes a single waiter up, if any.208 ///209 /// This is not 'sticky' in the sense that if no thread is waiting, the notification is lost210 /// completely (as opposed to automatically waking up the next waiter).211 pub fn notify_one(&self) {212 self.notify(1);213 }214 215 /// Wakes all waiters up, if any.216 ///217 /// This is not 'sticky' in the sense that if no thread is waiting, the notification is lost218 /// completely (as opposed to automatically waking up the next waiter).219 pub fn notify_all(&self) {220 self.notify(0);221 }222}223 224/// The return type of `wait_timeout`.225pub enum CondVarTimeoutResult {226 /// The timeout was reached.227 Timeout,228 /// Somebody woke us up.229 Woken {230 /// Remaining sleep duration.231 jiffies: Jiffies,232 },233 /// A signal occurred.234 Signal {235 /// Remaining sleep duration.236 jiffies: Jiffies,237 },238}239