[PATCH v2] completion: Document that reinit_completion() must be called after complete_all()

[PATCH v2] completion: Document that reinit_completion() must be called after complete_all()

[Steven Rostedt]

The function complete_all() modifies the completion "done" variable to
UINT_MAX, and no other caller (wait_for_completion(), etc) will modify
it back to zero. That means that any call to complete_all() must have a
reinit_completion() before that completion can be used again.

Document this fact by the complete_all() function.

Also document that completion_done() will always return true if
complete_all() is called.

Signed-off-by: Steven Rostedt (VMware) <rostedt@goodmis.org>
---
diff --git a/kernel/sched/completion.c b/kernel/sched/completion.c
index 13fc5ae..2950f44 100644
--- a/kernel/sched/completion.c
+++ b/kernel/sched/completion.c
@@ -47,6 +47,13 @@ EXPORT_SYMBOL(complete);
  *
  * It may be assumed that this function implies a write memory barrier before
  * changing the task state if and only if any tasks are woken up.
+ *
+ * Since complete_all() sets the completion of @x permanently to done
+ * to allow multiple waiters to finish, a call to reinit_completion()
+ * must be used on @x if @x is to be used again. The code must make
+ * sure that all waiters have woken and finished before reinitializing
+ * @x. Also note that the function completion_done() can not be used
+ * to know if there are still waiters after complete_all() has been called.
  */
 void complete_all(struct completion *x)
 {
@@ -297,6 +304,7 @@ EXPORT_SYMBOL(try_wait_for_completion);
  *	Return: 0 if there are waiters (wait_for_completion() in progress)
  *		 1 if there are no waiters.
  *
+ *	Note, this will always return true if complete_all() was called on @X.
  */
 bool completion_done(struct completion *x)
 {

Re: [PATCH v2] completion: Document that reinit_completion() must be called after complete_all()

[Linus Torvalds]

On Wed, Aug 16, 2017 at 10:12 AM, Steven Rostedt <rostedt@goodmis.org> wrote:
> The function complete_all() modifies the completion "done" variable to
> UINT_MAX, and no other caller (wait_for_completion(), etc) will modify
> it back to zero. That means that any call to complete_all() must have a
> reinit_completion() before that completion can be used again.
>
> Document this fact by the complete_all() function.
>
> Also document that completion_done() will always return true if
> complete_all() is called.

Ack. Do I take it directly or is it indended for some other tree?

               Linus

Re: [PATCH v2] completion: Document that reinit_completion() must be called after complete_all()

[Steven Rostedt]

On Wed, 16 Aug 2017 10:18:27 -0700
Linus Torvalds <torvalds@linux-foundation.org> wrote:

> On Wed, Aug 16, 2017 at 10:12 AM, Steven Rostedt <rostedt@goodmis.org> wrote:
> > The function complete_all() modifies the completion "done" variable to
> > UINT_MAX, and no other caller (wait_for_completion(), etc) will modify
> > it back to zero. That means that any call to complete_all() must have a
> > reinit_completion() before that completion can be used again.
> >
> > Document this fact by the complete_all() function.
> >
> > Also document that completion_done() will always return true if
> > complete_all() is called.  
> 
> Ack. Do I take it directly or is it indended for some other tree?
> 
>                Linus

You can take it, if nobody else wants to.

Thanks!

-- Steve

Re: [PATCH v2] completion: Document that reinit_completion() must be called after complete_all()

[Ingo Molnar]

* Linus Torvalds <torvalds@linux-foundation.org> wrote:

> On Wed, Aug 16, 2017 at 10:12 AM, Steven Rostedt <rostedt@goodmis.org> wrote:
> > The function complete_all() modifies the completion "done" variable to
> > UINT_MAX, and no other caller (wait_for_completion(), etc) will modify
> > it back to zero. That means that any call to complete_all() must have a
> > reinit_completion() before that completion can be used again.
> >
> > Document this fact by the complete_all() function.
> >
> > Also document that completion_done() will always return true if
> > complete_all() is called.
> 
> Ack. Do I take it directly or is it indended for some other tree?

Will add it to the scheduler tree.

Thanks,

	Ingo

Re: [PATCH v2] completion: Document that reinit_completion() must be called after complete_all()

[Linus Torvalds]

On Wed, Aug 16, 2017 at 11:06 AM, Ingo Molnar <mingo@kernel.org> wrote:
>
> Will add it to the scheduler tree.

Heh, I already took it, but I hadn't pushed out yet, so I undid it
all, and will get it from you. It's not like it's some timing-critical
fix ;)

               Linus

[tip:sched/core] sched/completion: Document that reinit_completion() must be called after complete_all()

[tip-bot for Steven Rostedt]

Commit-ID:  9c8783201cb58e9af8ddeb0cc68f37b0a44ca16c
Gitweb:     http://git.kernel.org/tip/9c8783201cb58e9af8ddeb0cc68f37b0a44ca16c
Author:     Steven Rostedt <rostedt@goodmis.org>
AuthorDate: Wed, 16 Aug 2017 13:12:02 -0400
Committer:  Ingo Molnar <mingo@kernel.org>
CommitDate: Wed, 16 Aug 2017 20:08:10 +0200

sched/completion: Document that reinit_completion() must be called after complete_all()

The complete_all() function modifies the completion's "done" variable to
UINT_MAX, and no other caller (wait_for_completion(), etc) will modify
it back to zero. That means that any call to complete_all() must have a
reinit_completion() before that completion can be used again.

Document this fact by the complete_all() function.

Also document that completion_done() will always return true if
complete_all() is called.

Signed-off-by: Steven Rostedt (VMware) <rostedt@goodmis.org>
Acked-by: Linus Torvalds <torvalds@linux-foundation.org>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Thomas Gleixner <tglx@linutronix.de>
Link: http://lkml.kernel.org/r/20170816131202.195c2f4b@gandalf.local.home
Signed-off-by: Ingo Molnar <mingo@kernel.org>
---
 kernel/sched/completion.c | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/kernel/sched/completion.c b/kernel/sched/completion.c
index 13fc5ae..2950f44 100644
--- a/kernel/sched/completion.c
+++ b/kernel/sched/completion.c
@@ -47,6 +47,13 @@ EXPORT_SYMBOL(complete);
  *
  * It may be assumed that this function implies a write memory barrier before
  * changing the task state if and only if any tasks are woken up.
+ *
+ * Since complete_all() sets the completion of @x permanently to done
+ * to allow multiple waiters to finish, a call to reinit_completion()
+ * must be used on @x if @x is to be used again. The code must make
+ * sure that all waiters have woken and finished before reinitializing
+ * @x. Also note that the function completion_done() can not be used
+ * to know if there are still waiters after complete_all() has been called.
  */
 void complete_all(struct completion *x)
 {
@@ -297,6 +304,7 @@ EXPORT_SYMBOL(try_wait_for_completion);
  *	Return: 0 if there are waiters (wait_for_completion() in progress)
  *		 1 if there are no waiters.
  *
+ *	Note, this will always return true if complete_all() was called on @X.
  */
 bool completion_done(struct completion *x)
 {