Commit 6f63904c8f3e ("sched: add a few helpers to wake up tasks on the
current cpu") introduced this new function to the completion API that
has not been documented yet.

Document complete_on_current_cpu() explaining what it does and when its
usage is justified.

Signed-off-by: Javier Carrasco <javier.carrasco.cruz@gmail.com>

---
Changes in v2:
- Rebase onto v6.17-rc1
- Fix patch formatting (drop --- before the Signed-off-by tag).
- Link to v1: https://lore.kernel.org/r/20250703-complete_on_current_cpu_doc-v1-1-262dc859b38a@gmail.com
---
 Documentation/scheduler/completion.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/scheduler/completion.rst b/Documentation/scheduler/completion.rst
index adf0c0a56d02..db9c131f0b62 100644
--- a/Documentation/scheduler/completion.rst
+++ b/Documentation/scheduler/completion.rst
@@ -272,6 +272,10 @@ Signaling completion from IRQ context is fine as it will appropriately
 lock with spin_lock_irqsave()/spin_unlock_irqrestore() and it will never
 sleep.
 
+Use complete_on_current_cpu() to wake up the task on the current CPU.
+It makes use of the WF_CURRENT_CPU flag to move the task to be woken up
+to the current CPU, achieving faster context switches. To use this variant,
+the context switch speed must be relevant and the optimization justified.
 
 try_wait_for_completion()/completion_done():
 --------------------------------------------

---
base-commit: 8f5ae30d69d7543eee0d70083daf4de8fe15d585
change-id: 20250702-complete_on_current_cpu_doc-94dfc72a39f8

Best regards,
--  
Javier Carrasco <javier.carrasco.cruz@gmail.com>

On Sun, Aug 24, 2025 at 6:38 AM Javier Carrasco
<javier.carrasco.cruz@gmail.com> wrote:
>
> Commit 6f63904c8f3e ("sched: add a few helpers to wake up tasks on the
> current cpu") introduced this new function to the completion API that
> has not been documented yet.
>
> Document complete_on_current_cpu() explaining what it does and when its
> usage is justified.
>
> Signed-off-by: Javier Carrasco <javier.carrasco.cruz@gmail.com>
>
> ---
> Changes in v2:
> - Rebase onto v6.17-rc1
> - Fix patch formatting (drop --- before the Signed-off-by tag).
> - Link to v1: https://lore.kernel.org/r/20250703-complete_on_current_cpu_doc-v1-1-262dc859b38a@gmail.com
> ---
>  Documentation/scheduler/completion.rst | 4 ++++
>  1 file changed, 4 insertions(+)
>
> diff --git a/Documentation/scheduler/completion.rst b/Documentation/scheduler/completion.rst
> index adf0c0a56d02..db9c131f0b62 100644
> --- a/Documentation/scheduler/completion.rst
> +++ b/Documentation/scheduler/completion.rst
> @@ -272,6 +272,10 @@ Signaling completion from IRQ context is fine as it will appropriately
>  lock with spin_lock_irqsave()/spin_unlock_irqrestore() and it will never
>  sleep.
>
> +Use complete_on_current_cpu() to wake up the task on the current CPU.
> +It makes use of the WF_CURRENT_CPU flag to move the task to be woken up
> +to the current CPU, achieving faster context switches. To use this variant,
> +the context switch speed must be relevant and the optimization justified.

I think it's worth mentioning that this only makes sense if the
current task falls
asleep right after it wakes up the target task.

>
>  try_wait_for_completion()/completion_done():
>  --------------------------------------------
>
> ---
> base-commit: 8f5ae30d69d7543eee0d70083daf4de8fe15d585
> change-id: 20250702-complete_on_current_cpu_doc-94dfc72a39f8
>
> Best regards,
> --
> Javier Carrasco <javier.carrasco.cruz@gmail.com>
>
>

Javier Carrasco <javier.carrasco.cruz@gmail.com> writes:

> Commit 6f63904c8f3e ("sched: add a few helpers to wake up tasks on the
> current cpu") introduced this new function to the completion API that
> has not been documented yet.

For a change like this, it is a really good idea to copy the author of
the original patch and others who were involved in it; I have added them
now.

jon

> Document complete_on_current_cpu() explaining what it does and when its
> usage is justified.
>
> Signed-off-by: Javier Carrasco <javier.carrasco.cruz@gmail.com>
>
> ---
> Changes in v2:
> - Rebase onto v6.17-rc1
> - Fix patch formatting (drop --- before the Signed-off-by tag).
> - Link to v1: https://lore.kernel.org/r/20250703-complete_on_current_cpu_doc-v1-1-262dc859b38a@gmail.com
> ---
>  Documentation/scheduler/completion.rst | 4 ++++
>  1 file changed, 4 insertions(+)
>
> diff --git a/Documentation/scheduler/completion.rst b/Documentation/scheduler/completion.rst
> index adf0c0a56d02..db9c131f0b62 100644
> --- a/Documentation/scheduler/completion.rst
> +++ b/Documentation/scheduler/completion.rst
> @@ -272,6 +272,10 @@ Signaling completion from IRQ context is fine as it will appropriately
>  lock with spin_lock_irqsave()/spin_unlock_irqrestore() and it will never
>  sleep.
>  
> +Use complete_on_current_cpu() to wake up the task on the current CPU.
> +It makes use of the WF_CURRENT_CPU flag to move the task to be woken up
> +to the current CPU, achieving faster context switches. To use this variant,
> +the context switch speed must be relevant and the optimization justified.
>  
>  try_wait_for_completion()/completion_done():
>  --------------------------------------------
>
> ---
> base-commit: 8f5ae30d69d7543eee0d70083daf4de8fe15d585
> change-id: 20250702-complete_on_current_cpu_doc-94dfc72a39f8
>
> Best regards,
> --  
> Javier Carrasco <javier.carrasco.cruz@gmail.com>

On Fri, Aug 29, 2025 at 04:44:28PM -0600, Jonathan Corbet wrote:
> Javier Carrasco <javier.carrasco.cruz@gmail.com> writes:
> 
> > Commit 6f63904c8f3e ("sched: add a few helpers to wake up tasks on the
> > current cpu") introduced this new function to the completion API that
> > has not been documented yet.
> 
> For a change like this, it is a really good idea to copy the author of
> the original patch and others who were involved in it; I have added them
> now.

This really is a rather specialized thing -- not sure it makes sense to
have in the document.

> > Document complete_on_current_cpu() explaining what it does and when its
> > usage is justified.
> >
> > Signed-off-by: Javier Carrasco <javier.carrasco.cruz@gmail.com>
> >
> > ---
> > Changes in v2:
> > - Rebase onto v6.17-rc1
> > - Fix patch formatting (drop --- before the Signed-off-by tag).
> > - Link to v1: https://lore.kernel.org/r/20250703-complete_on_current_cpu_doc-v1-1-262dc859b38a@gmail.com
> > ---
> >  Documentation/scheduler/completion.rst | 4 ++++
> >  1 file changed, 4 insertions(+)
> >
> > diff --git a/Documentation/scheduler/completion.rst b/Documentation/scheduler/completion.rst
> > index adf0c0a56d02..db9c131f0b62 100644
> > --- a/Documentation/scheduler/completion.rst
> > +++ b/Documentation/scheduler/completion.rst
> > @@ -272,6 +272,10 @@ Signaling completion from IRQ context is fine as it will appropriately
> >  lock with spin_lock_irqsave()/spin_unlock_irqrestore() and it will never
> >  sleep.
> >  
> > +Use complete_on_current_cpu() to wake up the task on the current CPU.
> > +It makes use of the WF_CURRENT_CPU flag to move the task to be woken up
> > +to the current CPU, achieving faster context switches. To use this variant,
> > +the context switch speed must be relevant and the optimization justified.
> >  
> >  try_wait_for_completion()/completion_done():
> >  --------------------------------------------
> >
> > ---
> > base-commit: 8f5ae30d69d7543eee0d70083daf4de8fe15d585
> > change-id: 20250702-complete_on_current_cpu_doc-94dfc72a39f8
> >
> > Best regards,
> > --  
> > Javier Carrasco <javier.carrasco.cruz@gmail.com>

On Sun Aug 31, 2025 at 3:07 AM CST, Peter Zijlstra wrote:
> On Fri, Aug 29, 2025 at 04:44:28PM -0600, Jonathan Corbet wrote:
>> Javier Carrasco <javier.carrasco.cruz@gmail.com> writes:
>> 
>> > Commit 6f63904c8f3e ("sched: add a few helpers to wake up tasks on the
>> > current cpu") introduced this new function to the completion API that
>> > has not been documented yet.
>> 
>> For a change like this, it is a really good idea to copy the author of
>> the original patch and others who were involved in it; I have added them
>> now.
>
> This really is a rather specialized thing -- not sure it makes sense to
> have in the document.
>

Hello Peter, thank you for your reply.

I agree that it is a rather specialized function, but in my opinion that
should not be a reason to exclude it from the documentation. Where do
you draw the line then? It is an exposed function from the API that can
be called like any other function from the API if the user requires that.


This one is by the way the only undocumented function from the completion
API.

Best regards,
Javier Carrasco