From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752662AbdHPSRf (ORCPT ); Wed, 16 Aug 2017 14:17:35 -0400 Received: from terminus.zytor.com ([65.50.211.136]:49135 "EHLO terminus.zytor.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752130AbdHPSRd (ORCPT ); Wed, 16 Aug 2017 14:17:33 -0400 Date: Wed, 16 Aug 2017 11:12:51 -0700 From: tip-bot for Steven Rostedt Message-ID: Cc: tglx@linutronix.de, peterz@infradead.org, rostedt@goodmis.org, paulmck@linux.vnet.ibm.com, akpm@linux-foundation.org, linux-kernel@vger.kernel.org, mingo@kernel.org, hpa@zytor.com, torvalds@linux-foundation.org Reply-To: linux-kernel@vger.kernel.org, torvalds@linux-foundation.org, hpa@zytor.com, mingo@kernel.org, paulmck@linux.vnet.ibm.com, rostedt@goodmis.org, peterz@infradead.org, tglx@linutronix.de, akpm@linux-foundation.org In-Reply-To: <20170816131202.195c2f4b@gandalf.local.home> References: <20170816131202.195c2f4b@gandalf.local.home> To: linux-tip-commits@vger.kernel.org Subject: [tip:sched/core] sched/completion: Document that reinit_completion() must be called after complete_all() Git-Commit-ID: 9c8783201cb58e9af8ddeb0cc68f37b0a44ca16c X-Mailer: tip-git-log-daemon Robot-ID: Robot-Unsubscribe: Contact to get blacklisted from these emails MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Content-Type: text/plain; charset=UTF-8 Content-Disposition: inline Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Commit-ID: 9c8783201cb58e9af8ddeb0cc68f37b0a44ca16c Gitweb: http://git.kernel.org/tip/9c8783201cb58e9af8ddeb0cc68f37b0a44ca16c Author: Steven Rostedt AuthorDate: Wed, 16 Aug 2017 13:12:02 -0400 Committer: Ingo Molnar 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) Acked-by: Linus Torvalds Cc: Andrew Morton Cc: Paul E. McKenney Cc: Peter Zijlstra Cc: Thomas Gleixner Link: http://lkml.kernel.org/r/20170816131202.195c2f4b@gandalf.local.home Signed-off-by: Ingo Molnar --- 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) {