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