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 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 to 34/// atomically release the given lock and go to sleep. It reacquires the lock when it wakes up. And 35/// it wakes up when notified by another thread (via [`CondVar::notify_one`] or 36/// [`CondVar::notify_all`]) or because the thread received a signal. It may also wake up 37/// spuriously. 38/// 39/// Instances of [`CondVar`] need a lock class and to be pinned. The recommended way to create such 40/// instances is with the [`pin_init`](crate::pin_init) and [`new_condvar`] macros. 41/// 42/// # Examples 43/// 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.h 82#[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 is 88 /// self-referential, so it cannot be safely moved once it is initialised. 89 /// 90 /// [`struct list_head`]: srctree/include/linux/types.h 91 #[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 threads 100// 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` have 109 // 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 ret 139 } 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 the 144 /// thread to sleep, reacquiring the lock on wake up. It wakes up when notified by 145 /// [`CondVar::notify_one`] or [`CondVar::notify_all`]. Note that it may also wake up 146 /// 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 may 154 /// 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 the 166 /// thread to sleep. It wakes up when notified by [`CondVar::notify_one`] or 167 /// [`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 the 200 /// current thread is about to go to sleep, so it should schedule the target thread on the same 201 /// 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 lost 210 /// 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 lost 218 /// 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