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_uninterruptible(&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`]: ../../../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 #[allow(clippy::new_ret_no_self)] 95 pub fn new(name: &'static CStr, key: &'static LockClassKey) -> impl PinInit<Self> { 96 pin_init!(Self { 97 _pin: PhantomPinned, 98 // SAFETY: `slot` is valid while the closure is called and both `name` and `key` have 99 // static lifetimes so they live indefinitely. 100 wait_list <- Opaque::ffi_init(|slot| unsafe { 101 bindings::__init_waitqueue_head(slot, name.as_char_ptr(), key.as_ptr()) 102 }), 103 }) 104 } 105 106 fn wait_internal<T: ?Sized, B: Backend>(&self, wait_state: u32, guard: &mut Guard<'_, T, B>) { 107 let wait = Opaque::<bindings::wait_queue_entry>::uninit(); 108 109 // SAFETY: `wait` points to valid memory. 110 unsafe { bindings::init_wait(wait.get()) }; 111 112 // SAFETY: Both `wait` and `wait_list` point to valid memory. 113 unsafe { 114 bindings::prepare_to_wait_exclusive(self.wait_list.get(), wait.get(), wait_state as _) 115 }; 116 117 // SAFETY: No arguments, switches to another thread. 118 guard.do_unlocked(|| unsafe { bindings::schedule() }); 119 120 // SAFETY: Both `wait` and `wait_list` point to valid memory. 121 unsafe { bindings::finish_wait(self.wait_list.get(), wait.get()) }; 122 } 123 124 /// Releases the lock and waits for a notification in interruptible mode. 125 /// 126 /// Atomically releases the given lock (whose ownership is proven by the guard) and puts the 127 /// thread to sleep, reacquiring the lock on wake up. It wakes up when notified by 128 /// [`CondVar::notify_one`] or [`CondVar::notify_all`], or when the thread receives a signal. 129 /// It may also wake up spuriously. 130 /// 131 /// Returns whether there is a signal pending. 132 #[must_use = "wait returns if a signal is pending, so the caller must check the return value"] 133 pub fn wait<T: ?Sized, B: Backend>(&self, guard: &mut Guard<'_, T, B>) -> bool { 134 self.wait_internal(bindings::TASK_INTERRUPTIBLE, guard); 135 crate::current!().signal_pending() 136 } 137 138 /// Releases the lock and waits for a notification in uninterruptible mode. 139 /// 140 /// Similar to [`CondVar::wait`], except that the wait is not interruptible. That is, the 141 /// thread won't wake up due to signals. It may, however, wake up supirously. 142 pub fn wait_uninterruptible<T: ?Sized, B: Backend>(&self, guard: &mut Guard<'_, T, B>) { 143 self.wait_internal(bindings::TASK_UNINTERRUPTIBLE, guard) 144 } 145 146 /// Calls the kernel function to notify the appropriate number of threads with the given flags. 147 fn notify(&self, count: i32, flags: u32) { 148 // SAFETY: `wait_list` points to valid memory. 149 unsafe { 150 bindings::__wake_up( 151 self.wait_list.get(), 152 bindings::TASK_NORMAL, 153 count, 154 flags as _, 155 ) 156 }; 157 } 158 159 /// Wakes a single waiter up, if any. 160 /// 161 /// This is not 'sticky' in the sense that if no thread is waiting, the notification is lost 162 /// completely (as opposed to automatically waking up the next waiter). 163 pub fn notify_one(&self) { 164 self.notify(1, 0); 165 } 166 167 /// Wakes all waiters up, if any. 168 /// 169 /// This is not 'sticky' in the sense that if no thread is waiting, the notification is lost 170 /// completely (as opposed to automatically waking up the next waiter). 171 pub fn notify_all(&self) { 172 self.notify(0, 0); 173 } 174 } 175