Re: [PATCH 3/4] rust: completion: add complete()

[Gary Guo]

On Sun Jun 14, 2026 at 4:59 PM BST, Maurice Hieronymus wrote:
> The initial completion abstraction only added complete_all() and
> wait_for_completion(). complete_all() marks the completion permanently
> done, which makes a single Completion unsuitable for signalling the same
> event repeatedly: once complete_all() has run, every subsequent
> wait_for_completion() returns immediately without waiting.
>
> Add complete(), which wakes a single waiter and increments the internal
> counter by one. Paired one-to-one with wait_for_completion(), it allows
> the same completion to be reused across multiple cycles, e.g. to wait for
> consecutive DMA transfers to finish.
>
> Signed-off-by: Maurice Hieronymus <mhi@xxxxxxxxxxx>
> ---
>  rust/kernel/sync/completion.rs | 14 ++++++++++++++
>  1 file changed, 14 insertions(+)
>
> diff --git a/rust/kernel/sync/completion.rs b/rust/kernel/sync/completion.rs
> index c50012a940a3..b386b84222f9 100644
> --- a/rust/kernel/sync/completion.rs
> +++ b/rust/kernel/sync/completion.rs
> @@ -90,6 +90,20 @@ fn as_raw(&self) -> *mut bindings::completion {
>          self.inner.get()
>      }
>  
> +    /// Signal one task waiting on this completion.

"Signal a single task" to put some emphasis on "single".

> +    ///
> +    /// This method wakes up a single task waiting on this completion and increments the
> +    /// internal counter by one. If no task is currently waiting, the next

Why does this need to mention about its implementation detail? The user of the
API doesn't need to care.

> +    /// [`Completion::wait_for_completion`] returns immediately.
> +    ///
> +    /// Unlike [`Completion::complete_all`], the completion is not marked permanently done, so a
> +    /// single [`Completion`] paired one-to-one with [`Completion::wait_for_completion`] can be
> +    /// reused to signal the same event repeatedly.

Hmm, I don't think the behaviour of `complete_all` needs to be in the
documentation of `complete`.

On the other note, you probably should update documentation of
`wait_for_completion` to also mention `complete`.

Best,
Gary

> +    pub fn complete(&self) {
> +        // SAFETY: `self.as_raw()` is a pointer to a valid `struct completion`.
> +        unsafe { bindings::complete(self.as_raw()) };
> +    }
> +
>      /// Signal all tasks waiting on this completion.
>      ///
>      /// This method wakes up all tasks waiting on this completion; after this operation the