[PATCH] sched: document wait_for_completion_* return values

[PATCH] sched: document wait_for_completion_* return values

[J. Bruce Fields]

From: J. Bruce Fields <bfields@redhat.com>

The return-value convention for these functions varies depending on
whether they're interruptible or can timeout.  It can be a little
confusing--document it.

Signed-off-by: J. Bruce Fields <bfields@redhat.com>
---
 kernel/sched.c |   13 +++++++++++++
 1 files changed, 13 insertions(+), 0 deletions(-)

diff --git a/kernel/sched.c b/kernel/sched.c
index ccacdbd..ee84344 100644
--- a/kernel/sched.c
+++ b/kernel/sched.c
@@ -4690,6 +4690,9 @@ EXPORT_SYMBOL(wait_for_completion);
  * This waits for either a completion of a specific task to be signaled or for a
  * specified timeout to expire. The timeout is in jiffies. It is not
  * interruptible.
+ *
+ * The return value is 0 if timed out, and positive (at least 1, or number of
+ * jiffies left till timeout) if completed.
  */
 unsigned long __sched
 wait_for_completion_timeout(struct completion *x, unsigned long timeout)
@@ -4704,6 +4707,8 @@ EXPORT_SYMBOL(wait_for_completion_timeout);
  *
  * This waits for completion of a specific task to be signaled. It is
  * interruptible.
+ *
+ * The return value is -ERESTARTSYS if interrupted, 0 if completed.
  */
 int __sched wait_for_completion_interruptible(struct completion *x)
 {
@@ -4721,6 +4726,9 @@ EXPORT_SYMBOL(wait_for_completion_interruptible);
  *
  * This waits for either a completion of a specific task to be signaled or for a
  * specified timeout to expire. It is interruptible. The timeout is in jiffies.
+ *
+ * The return value is -ERESTARTSYS if interrupted, 0 if timed out,
+ * positive (at least 1, or number of jiffies left till timeout) if completed.
  */
 long __sched
 wait_for_completion_interruptible_timeout(struct completion *x,
@@ -4736,6 +4744,8 @@ EXPORT_SYMBOL(wait_for_completion_interruptible_timeout);
  *
  * This waits to be signaled for completion of a specific task. It can be
  * interrupted by a kill signal.
+ *
+ * The return value is -ERESTARTSYS if interrupted, 0 if completed.
  */
 int __sched wait_for_completion_killable(struct completion *x)
 {
@@ -4754,6 +4764,9 @@ EXPORT_SYMBOL(wait_for_completion_killable);
  * This waits for either a completion of a specific task to be
  * signaled or for a specified timeout to expire. It can be
  * interrupted by a kill signal. The timeout is in jiffies.
+ *
+ * The return value is -ERESTARTSYS if interrupted, 0 if timed out,
+ * positive (at least 1, or number of jiffies left till timeout) if completed.
  */
 long __sched
 wait_for_completion_killable_timeout(struct completion *x,
-- 
1.7.4.1

Re: [PATCH] sched: document wait_for_completion_* return values

[J. Bruce Fields]

On Thu, Oct 06, 2011 at 03:22:46PM -0400, bfields wrote:
> From: J. Bruce Fields <bfields@redhat.com>
> 
> The return-value convention for these functions varies depending on
> whether they're interruptible or can timeout.  It can be a little
> confusing--document it.

Ping?  Should I resend this or send it someplace different?

--b.

> 
> Signed-off-by: J. Bruce Fields <bfields@redhat.com>
> ---
>  kernel/sched.c |   13 +++++++++++++
>  1 files changed, 13 insertions(+), 0 deletions(-)
> 
> diff --git a/kernel/sched.c b/kernel/sched.c
> index ccacdbd..ee84344 100644
> --- a/kernel/sched.c
> +++ b/kernel/sched.c
> @@ -4690,6 +4690,9 @@ EXPORT_SYMBOL(wait_for_completion);
>   * This waits for either a completion of a specific task to be signaled or for a
>   * specified timeout to expire. The timeout is in jiffies. It is not
>   * interruptible.
> + *
> + * The return value is 0 if timed out, and positive (at least 1, or number of
> + * jiffies left till timeout) if completed.
>   */
>  unsigned long __sched
>  wait_for_completion_timeout(struct completion *x, unsigned long timeout)
> @@ -4704,6 +4707,8 @@ EXPORT_SYMBOL(wait_for_completion_timeout);
>   *
>   * This waits for completion of a specific task to be signaled. It is
>   * interruptible.
> + *
> + * The return value is -ERESTARTSYS if interrupted, 0 if completed.
>   */
>  int __sched wait_for_completion_interruptible(struct completion *x)
>  {
> @@ -4721,6 +4726,9 @@ EXPORT_SYMBOL(wait_for_completion_interruptible);
>   *
>   * This waits for either a completion of a specific task to be signaled or for a
>   * specified timeout to expire. It is interruptible. The timeout is in jiffies.
> + *
> + * The return value is -ERESTARTSYS if interrupted, 0 if timed out,
> + * positive (at least 1, or number of jiffies left till timeout) if completed.
>   */
>  long __sched
>  wait_for_completion_interruptible_timeout(struct completion *x,
> @@ -4736,6 +4744,8 @@ EXPORT_SYMBOL(wait_for_completion_interruptible_timeout);
>   *
>   * This waits to be signaled for completion of a specific task. It can be
>   * interrupted by a kill signal.
> + *
> + * The return value is -ERESTARTSYS if interrupted, 0 if completed.
>   */
>  int __sched wait_for_completion_killable(struct completion *x)
>  {
> @@ -4754,6 +4764,9 @@ EXPORT_SYMBOL(wait_for_completion_killable);
>   * This waits for either a completion of a specific task to be
>   * signaled or for a specified timeout to expire. It can be
>   * interrupted by a kill signal. The timeout is in jiffies.
> + *
> + * The return value is -ERESTARTSYS if interrupted, 0 if timed out,
> + * positive (at least 1, or number of jiffies left till timeout) if completed.
>   */
>  long __sched
>  wait_for_completion_killable_timeout(struct completion *x,
> -- 
> 1.7.4.1
> 

Re: [PATCH] sched: document wait_for_completion_* return values

[Peter Zijlstra]

On Fri, 2011-10-28 at 04:43 -0400, J. Bruce Fields wrote:
> Ping?  Should I resend this or send it someplace different?

Its in my queue somewhere, conferences got in the way.

Re: [PATCH] sched: document wait_for_completion_* return values

[J. Bruce Fields]

On Fri, Oct 28, 2011 at 10:47:16AM +0200, Peter Zijlstra wrote:
> On Fri, 2011-10-28 at 04:43 -0400, J. Bruce Fields wrote:
> > Ping?  Should I resend this or send it someplace different?
> 
> Its in my queue somewhere, conferences got in the way.

Great, thanks!

--b.

[tip:sched/core] sched: Document wait_for_completion_*() return values

[tip-bot for J. Bruce Fields]

Commit-ID:  c6dc7f055d333ef35f397b8d7c3abcd1918bf8cb
Gitweb:     http://git.kernel.org/tip/c6dc7f055d333ef35f397b8d7c3abcd1918bf8cb
Author:     J. Bruce Fields <bfields@redhat.com>
AuthorDate: Thu, 6 Oct 2011 15:22:46 -0400
Committer:  Ingo Molnar <mingo@elte.hu>
CommitDate: Mon, 14 Nov 2011 12:50:37 +0100

sched: Document wait_for_completion_*() return values

The return-value convention for these functions varies depending on
whether they're interruptible or can timeout.  It can be a little
confusing--document it.

Signed-off-by: J. Bruce Fields <bfields@redhat.com>
Signed-off-by: Peter Zijlstra <a.p.zijlstra@chello.nl>
Link: http://lkml.kernel.org/r/20111006192246.GB28026@fieldses.org
Signed-off-by: Ingo Molnar <mingo@elte.hu>
---
 kernel/sched.c |   13 +++++++++++++
 1 files changed, 13 insertions(+), 0 deletions(-)

diff --git a/kernel/sched.c b/kernel/sched.c
index 0e9344a..3d2c436 100644
--- a/kernel/sched.c
+++ b/kernel/sched.c
@@ -4810,6 +4810,9 @@ EXPORT_SYMBOL(wait_for_completion);
  * This waits for either a completion of a specific task to be signaled or for a
  * specified timeout to expire. The timeout is in jiffies. It is not
  * interruptible.
+ *
+ * The return value is 0 if timed out, and positive (at least 1, or number of
+ * jiffies left till timeout) if completed.
  */
 unsigned long __sched
 wait_for_completion_timeout(struct completion *x, unsigned long timeout)
@@ -4824,6 +4827,8 @@ EXPORT_SYMBOL(wait_for_completion_timeout);
  *
  * This waits for completion of a specific task to be signaled. It is
  * interruptible.
+ *
+ * The return value is -ERESTARTSYS if interrupted, 0 if completed.
  */
 int __sched wait_for_completion_interruptible(struct completion *x)
 {
@@ -4841,6 +4846,9 @@ EXPORT_SYMBOL(wait_for_completion_interruptible);
  *
  * This waits for either a completion of a specific task to be signaled or for a
  * specified timeout to expire. It is interruptible. The timeout is in jiffies.
+ *
+ * The return value is -ERESTARTSYS if interrupted, 0 if timed out,
+ * positive (at least 1, or number of jiffies left till timeout) if completed.
  */
 long __sched
 wait_for_completion_interruptible_timeout(struct completion *x,
@@ -4856,6 +4864,8 @@ EXPORT_SYMBOL(wait_for_completion_interruptible_timeout);
  *
  * This waits to be signaled for completion of a specific task. It can be
  * interrupted by a kill signal.
+ *
+ * The return value is -ERESTARTSYS if interrupted, 0 if completed.
  */
 int __sched wait_for_completion_killable(struct completion *x)
 {
@@ -4874,6 +4884,9 @@ EXPORT_SYMBOL(wait_for_completion_killable);
  * This waits for either a completion of a specific task to be
  * signaled or for a specified timeout to expire. It can be
  * interrupted by a kill signal. The timeout is in jiffies.
+ *
+ * The return value is -ERESTARTSYS if interrupted, 0 if timed out,
+ * positive (at least 1, or number of jiffies left till timeout) if completed.
  */
 long __sched
 wait_for_completion_killable_timeout(struct completion *x,