projects/linux·blob uaccess-cleanups · refs

114 lines · 3.3 KiB

1// SPDX-License-Identifier: GPL-2.0
2
3//! Completion support.
4//!
5//! Reference: <https://docs.kernel.org/scheduler/completion.html>
6//!
7//! C header: [`include/linux/completion.h`](srctree/include/linux/completion.h)
8
9use crate::{bindings, prelude::*, types::Opaque};
10
11/// Synchronization primitive to signal when a certain task has been completed.
12///
13/// The [`Completion`] synchronization primitive signals when a certain task has been completed by
14/// waking up other tasks that have been queued up to wait for the [`Completion`] to be completed.
15///
16/// # Examples
17///
18/// ```
19/// use kernel::sync::{Arc, Completion};
20/// use kernel::workqueue::{self, impl_has_work, new_work, Work, WorkItem};
21///
22/// #[pin_data]
23/// struct MyTask {
24/// #[pin]
25/// work: Work<MyTask>,
26/// #[pin]
27/// done: Completion,
28/// }
29///
30/// impl_has_work! {
31/// impl HasWork<Self> for MyTask { self.work }
32/// }
33///
34/// impl MyTask {
35/// fn new() -> Result<Arc<Self>> {
36/// let this = Arc::pin_init(pin_init!(MyTask {
37/// work <- new_work!("MyTask::work"),
38/// done <- Completion::new(),
39/// }), GFP_KERNEL)?;
40///
41/// let _ = workqueue::system().enqueue(this.clone());
42///
43/// Ok(this)
44/// }
45///
46/// fn wait_for_completion(&self) {
47/// self.done.wait_for_completion();
48///
49/// pr_info!("Completion: task complete\n");
50/// }
51/// }
52///
53/// impl WorkItem for MyTask {
54/// type Pointer = Arc<MyTask>;
55///
56/// fn run(this: Arc<MyTask>) {
57/// // process this task
58/// this.done.complete_all();
59/// }
60/// }
61///
62/// let task = MyTask::new()?;
63/// task.wait_for_completion();
64/// # Ok::<(), Error>(())
65/// ```
66#[pin_data]
67pub struct Completion {
68 #[pin]
69 inner: Opaque<bindings::completion>,
70}
71
72// SAFETY: `Completion` is safe to be send to any task.
73unsafe impl Send for Completion {}
74
75// SAFETY: `Completion` is safe to be accessed concurrently.
76unsafe impl Sync for Completion {}
77
78impl Completion {
79 /// Create an initializer for a new [`Completion`].
80 pub fn new() -> impl PinInit<Self> {
81 pin_init!(Self {
82 inner <- Opaque::ffi_init(|slot: *mut bindings::completion| {
83 // SAFETY: `slot` is a valid pointer to an uninitialized `struct completion`.
84 unsafe { bindings::init_completion(slot) };
85 }),
86 })
87 }
88
89 fn as_raw(&self) -> *mut bindings::completion {
90 self.inner.get()
91 }
92
93 /// Signal all tasks waiting on this completion.
94 ///
95 /// This method wakes up all tasks waiting on this completion; after this operation the
96 /// completion is permanently done, i.e. signals all current and future waiters.
97 #[inline]
98 pub fn complete_all(&self) {
99 // SAFETY: `self.as_raw()` is a pointer to a valid `struct completion`.
100 unsafe { bindings::complete_all(self.as_raw()) };
101 }
102
103 /// Wait for completion of a task.
104 ///
105 /// This method waits for the completion of a task; it is not interruptible and there is no
106 /// timeout.
107 ///
108 /// See also [`Completion::complete_all`].
109 #[inline]
110 pub fn wait_for_completion(&self) {
111 // SAFETY: `self.as_raw()` is a pointer to a valid `struct completion`.
112 unsafe { bindings::wait_for_completion(self.as_raw()) };
113 }
114}