Something went wrong. Try again.
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259// SPDX-License-Identifier: GPL-2.0
//! A condition variable.//!//! This module allows Rust code to use the kernel's [`struct wait_queue_head`] as a condition//! variable.
use super::{lock::Backend, lock::Guard, LockClassKey};use crate::{ ffi::{c_int, c_long}, str::{CStr, CStrExt as _}, task::{ MAX_SCHEDULE_TIMEOUT, TASK_FREEZABLE, TASK_INTERRUPTIBLE, TASK_NORMAL, TASK_UNINTERRUPTIBLE, }, time::Jiffies, types::Opaque,};use core::{marker::PhantomPinned, pin::Pin, ptr};use pin_init::{pin_data, pin_init, PinInit};
/// Creates a [`CondVar`] initialiser with the given name and a newly-created lock class.#[macro_export]macro_rules! new_condvar { ($($name:literal)?) => { $crate::sync::CondVar::new($crate::optional_name!($($name)?), $crate::static_lock_class!()) };}pub use new_condvar;
/// A conditional variable.////// Exposes the kernel's [`struct wait_queue_head`] as a condition variable. It allows the caller to/// atomically release the given lock and go to sleep. It reacquires the lock when it wakes up. And/// it wakes up when notified by another thread (via [`CondVar::notify_one`] or/// [`CondVar::notify_all`]) or because the thread received a signal. It may also wake up/// spuriously.////// Instances of [`CondVar`] need a lock class and to be pinned. The recommended way to create such/// instances is with the [`pin_init`](pin_init::pin_init!) and [`new_condvar`] macros.////// # Examples////// The following is an example of using a condvar with a mutex:////// ```/// use kernel::sync::{new_condvar, new_mutex, CondVar, Mutex};////// #[pin_data]/// pub struct Example {/// #[pin]/// value: Mutex<u32>,////// #[pin]/// value_changed: CondVar,/// }////// /// Waits for `e.value` to become `v`./// fn wait_for_value(e: &Example, v: u32) {/// let mut guard = e.value.lock();/// while *guard != v {/// e.value_changed.wait(&mut guard);/// }/// }////// /// Increments `e.value` and notifies all potential waiters./// fn increment(e: &Example) {/// *e.value.lock() += 1;/// e.value_changed.notify_all();/// }////// /// Allocates a new boxed `Example`./// fn new_example() -> Result<Pin<KBox<Example>>> {/// KBox::pin_init(pin_init!(Example {/// value <- new_mutex!(0),/// value_changed <- new_condvar!(),/// }), GFP_KERNEL)/// }/// ```////// [`struct wait_queue_head`]: srctree/include/linux/wait.h#[pin_data]pub struct CondVar { #[pin] pub(crate) wait_queue_head: Opaque<bindings::wait_queue_head>,
/// A condvar needs to be pinned because it contains a [`struct list_head`] that is /// self-referential, so it cannot be safely moved once it is initialised. /// /// [`struct list_head`]: srctree/include/linux/types.h #[pin] _pin: PhantomPinned,}
// SAFETY: `CondVar` only uses a `struct wait_queue_head`, which is safe to use on any thread.unsafe impl Send for CondVar {}
// SAFETY: `CondVar` only uses a `struct wait_queue_head`, which is safe to use on multiple threads// concurrently.unsafe impl Sync for CondVar {}
impl CondVar { /// Constructs a new condvar initialiser. pub fn new(name: &'static CStr, key: Pin<&'static LockClassKey>) -> impl PinInit<Self> { pin_init!(Self { _pin: PhantomPinned, // SAFETY: `slot` is valid while the closure is called and both `name` and `key` have // static lifetimes so they live indefinitely. wait_queue_head <- Opaque::ffi_init(|slot| unsafe { bindings::__init_waitqueue_head(slot, name.as_char_ptr(), key.as_ptr()) }), }) }
fn wait_internal<T: ?Sized, B: Backend>( &self, wait_state: c_int, guard: &mut Guard<'_, T, B>, timeout_in_jiffies: c_long, ) -> c_long { let wait = Opaque::<bindings::wait_queue_entry>::uninit();
// SAFETY: `wait` points to valid memory. unsafe { bindings::init_wait(wait.get()) };
// SAFETY: Both `wait` and `wait_queue_head` point to valid memory. unsafe { bindings::prepare_to_wait_exclusive(self.wait_queue_head.get(), wait.get(), wait_state) };
// SAFETY: Switches to another thread. The timeout can be any number. let ret = guard.do_unlocked(|| unsafe { bindings::schedule_timeout(timeout_in_jiffies) });
// SAFETY: Both `wait` and `wait_queue_head` point to valid memory. unsafe { bindings::finish_wait(self.wait_queue_head.get(), wait.get()) };
ret }
/// Releases the lock and waits for a notification in uninterruptible mode. /// /// Atomically releases the given lock (whose ownership is proven by the guard) and puts the /// thread to sleep, reacquiring the lock on wake up. It wakes up when notified by /// [`CondVar::notify_one`] or [`CondVar::notify_all`]. Note that it may also wake up /// spuriously. pub fn wait<T: ?Sized, B: Backend>(&self, guard: &mut Guard<'_, T, B>) { self.wait_internal(TASK_UNINTERRUPTIBLE, guard, MAX_SCHEDULE_TIMEOUT); }
/// Releases the lock and waits for a notification in interruptible mode. /// /// Similar to [`CondVar::wait`], except that the wait is interruptible. That is, the thread may /// wake up due to signals. It may also wake up spuriously. /// /// Returns whether there is a signal pending. #[must_use = "wait_interruptible returns if a signal is pending, so the caller must check the return value"] pub fn wait_interruptible<T: ?Sized, B: Backend>(&self, guard: &mut Guard<'_, T, B>) -> bool { self.wait_internal(TASK_INTERRUPTIBLE, guard, MAX_SCHEDULE_TIMEOUT); crate::current!().signal_pending() }
/// Releases the lock and waits for a notification in interruptible and freezable mode. /// /// The process is allowed to be frozen during this sleep. No lock should be held when calling /// this function, and there is a lockdep assertion for this. Freezing a task that holds a lock /// can trivially deadlock vs another task that needs that lock to complete before it too can /// hit freezable. #[must_use = "wait_interruptible_freezable returns if a signal is pending, so the caller must check the return value"] pub fn wait_interruptible_freezable<T: ?Sized, B: Backend>( &self, guard: &mut Guard<'_, T, B>, ) -> bool { self.wait_internal( TASK_INTERRUPTIBLE | TASK_FREEZABLE, guard, MAX_SCHEDULE_TIMEOUT, ); crate::current!().signal_pending() }
/// Releases the lock and waits for a notification in interruptible mode. /// /// Atomically releases the given lock (whose ownership is proven by the guard) and puts the /// thread to sleep. It wakes up when notified by [`CondVar::notify_one`] or /// [`CondVar::notify_all`], or when a timeout occurs, or when the thread receives a signal. #[must_use = "wait_interruptible_timeout returns if a signal is pending, so the caller must check the return value"] pub fn wait_interruptible_timeout<T: ?Sized, B: Backend>( &self, guard: &mut Guard<'_, T, B>, jiffies: Jiffies, ) -> CondVarTimeoutResult { let jiffies = jiffies.try_into().unwrap_or(MAX_SCHEDULE_TIMEOUT); let res = self.wait_internal(TASK_INTERRUPTIBLE, guard, jiffies);
match (res as Jiffies, crate::current!().signal_pending()) { (jiffies, true) => CondVarTimeoutResult::Signal { jiffies }, (0, false) => CondVarTimeoutResult::Timeout, (jiffies, false) => CondVarTimeoutResult::Woken { jiffies }, } }
/// Calls the kernel function to notify the appropriate number of threads. fn notify(&self, count: c_int) { // SAFETY: `wait_queue_head` points to valid memory. unsafe { bindings::__wake_up( self.wait_queue_head.get(), TASK_NORMAL, count, ptr::null_mut(), ) }; }
/// Calls the kernel function to notify one thread synchronously. /// /// This method behaves like `notify_one`, except that it hints to the scheduler that the /// current thread is about to go to sleep, so it should schedule the target thread on the same /// CPU. #[inline] pub fn notify_sync(&self) { // SAFETY: `wait_queue_head` points to valid memory. unsafe { bindings::__wake_up_sync(self.wait_queue_head.get(), TASK_NORMAL) }; }
/// Wakes a single waiter up, if any. /// /// This is not 'sticky' in the sense that if no thread is waiting, the notification is lost /// completely (as opposed to automatically waking up the next waiter). #[inline] pub fn notify_one(&self) { self.notify(1); }
/// Wakes all waiters up, if any. /// /// This is not 'sticky' in the sense that if no thread is waiting, the notification is lost /// completely (as opposed to automatically waking up the next waiter). #[inline] pub fn notify_all(&self) { self.notify(0); }}
/// The return type of `wait_timeout`.pub enum CondVarTimeoutResult { /// The timeout was reached. Timeout, /// Somebody woke us up. Woken { /// Remaining sleep duration. jiffies: Jiffies, }, /// A signal occurred. Signal { /// Remaining sleep duration. jiffies: Jiffies, },}