Loading...
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 init::PinInit,
12 pin_init,
13 str::CStr,
14 task::{MAX_SCHEDULE_TIMEOUT, TASK_INTERRUPTIBLE, TASK_NORMAL, TASK_UNINTERRUPTIBLE},
15 time::Jiffies,
16 types::Opaque,
17};
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<KBox<Example>>> {
74/// KBox::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.
96unsafe impl Send for CondVar {}
97
98// SAFETY: `CondVar` only uses a `struct wait_queue_head`, which is safe to use on multiple threads
99// concurrently.
100unsafe impl Sync for CondVar {}
101
102impl CondVar {
103 /// Constructs a new condvar initialiser.
104 pub fn new(name: &'static CStr, key: &'static LockClassKey) -> impl PinInit<Self> {
105 pin_init!(Self {
106 _pin: PhantomPinned,
107 // SAFETY: `slot` is valid while the closure is called and both `name` and `key` have
108 // static lifetimes so they live indefinitely.
109 wait_queue_head <- Opaque::ffi_init(|slot| unsafe {
110 bindings::__init_waitqueue_head(slot, name.as_char_ptr(), key.as_ptr())
111 }),
112 })
113 }
114
115 fn wait_internal<T: ?Sized, B: Backend>(
116 &self,
117 wait_state: c_int,
118 guard: &mut Guard<'_, T, B>,
119 timeout_in_jiffies: c_long,
120 ) -> c_long {
121 let wait = Opaque::<bindings::wait_queue_entry>::uninit();
122
123 // SAFETY: `wait` points to valid memory.
124 unsafe { bindings::init_wait(wait.get()) };
125
126 // SAFETY: Both `wait` and `wait_queue_head` point to valid memory.
127 unsafe {
128 bindings::prepare_to_wait_exclusive(self.wait_queue_head.get(), wait.get(), wait_state)
129 };
130
131 // SAFETY: Switches to another thread. The timeout can be any number.
132 let ret = guard.do_unlocked(|| unsafe { bindings::schedule_timeout(timeout_in_jiffies) });
133
134 // SAFETY: Both `wait` and `wait_queue_head` point to valid memory.
135 unsafe { bindings::finish_wait(self.wait_queue_head.get(), wait.get()) };
136
137 ret
138 }
139
140 /// Releases the lock and waits for a notification in uninterruptible mode.
141 ///
142 /// Atomically releases the given lock (whose ownership is proven by the guard) and puts the
143 /// thread to sleep, reacquiring the lock on wake up. It wakes up when notified by
144 /// [`CondVar::notify_one`] or [`CondVar::notify_all`]. Note that it may also wake up
145 /// spuriously.
146 pub fn wait<T: ?Sized, B: Backend>(&self, guard: &mut Guard<'_, T, B>) {
147 self.wait_internal(TASK_UNINTERRUPTIBLE, guard, MAX_SCHEDULE_TIMEOUT);
148 }
149
150 /// Releases the lock and waits for a notification in interruptible mode.
151 ///
152 /// Similar to [`CondVar::wait`], except that the wait is interruptible. That is, the thread may
153 /// wake up due to signals. It may also wake up spuriously.
154 ///
155 /// Returns whether there is a signal pending.
156 #[must_use = "wait_interruptible returns if a signal is pending, so the caller must check the return value"]
157 pub fn wait_interruptible<T: ?Sized, B: Backend>(&self, guard: &mut Guard<'_, T, B>) -> bool {
158 self.wait_internal(TASK_INTERRUPTIBLE, guard, MAX_SCHEDULE_TIMEOUT);
159 crate::current!().signal_pending()
160 }
161
162 /// Releases the lock and waits for a notification in interruptible mode.
163 ///
164 /// Atomically releases the given lock (whose ownership is proven by the guard) and puts the
165 /// thread to sleep. It wakes up when notified by [`CondVar::notify_one`] or
166 /// [`CondVar::notify_all`], or when a timeout occurs, or when the thread receives a signal.
167 #[must_use = "wait_interruptible_timeout returns if a signal is pending, so the caller must check the return value"]
168 pub fn wait_interruptible_timeout<T: ?Sized, B: Backend>(
169 &self,
170 guard: &mut Guard<'_, T, B>,
171 jiffies: Jiffies,
172 ) -> CondVarTimeoutResult {
173 let jiffies = jiffies.try_into().unwrap_or(MAX_SCHEDULE_TIMEOUT);
174 let res = self.wait_internal(TASK_INTERRUPTIBLE, guard, jiffies);
175
176 match (res as Jiffies, crate::current!().signal_pending()) {
177 (jiffies, true) => CondVarTimeoutResult::Signal { jiffies },
178 (0, false) => CondVarTimeoutResult::Timeout,
179 (jiffies, false) => CondVarTimeoutResult::Woken { jiffies },
180 }
181 }
182
183 /// Calls the kernel function to notify the appropriate number of threads.
184 fn notify(&self, count: c_int) {
185 // SAFETY: `wait_queue_head` points to valid memory.
186 unsafe {
187 bindings::__wake_up(
188 self.wait_queue_head.get(),
189 TASK_NORMAL,
190 count,
191 ptr::null_mut(),
192 )
193 };
194 }
195
196 /// Calls the kernel function to notify one thread synchronously.
197 ///
198 /// This method behaves like `notify_one`, except that it hints to the scheduler that the
199 /// current thread is about to go to sleep, so it should schedule the target thread on the same
200 /// CPU.
201 pub fn notify_sync(&self) {
202 // SAFETY: `wait_queue_head` points to valid memory.
203 unsafe { bindings::__wake_up_sync(self.wait_queue_head.get(), TASK_NORMAL) };
204 }
205
206 /// Wakes a single waiter up, if any.
207 ///
208 /// This is not 'sticky' in the sense that if no thread is waiting, the notification is lost
209 /// completely (as opposed to automatically waking up the next waiter).
210 pub fn notify_one(&self) {
211 self.notify(1);
212 }
213
214 /// Wakes all waiters up, if any.
215 ///
216 /// This is not 'sticky' in the sense that if no thread is waiting, the notification is lost
217 /// completely (as opposed to automatically waking up the next waiter).
218 pub fn notify_all(&self) {
219 self.notify(0);
220 }
221}
222
223/// The return type of `wait_timeout`.
224pub enum CondVarTimeoutResult {
225 /// The timeout was reached.
226 Timeout,
227 /// Somebody woke us up.
228 Woken {
229 /// Remaining sleep duration.
230 jiffies: Jiffies,
231 },
232 /// A signal occurred.
233 Signal {
234 /// Remaining sleep duration.
235 jiffies: Jiffies,
236 },
237}
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::{bindings, init::PinInit, pin_init, str::CStr, types::Opaque};
10use core::marker::PhantomPinned;
11use macros::pin_data;
12
13/// Creates a [`CondVar`] initialiser with the given name and a newly-created lock class.
14#[macro_export]
15macro_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]
74pub 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)]
86unsafe 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.
90unsafe impl Sync for CondVar {}
91
92impl 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}