Re: [Fwd: Corrections please ...]

[Dave Chinner <david@fromorbit.com>]

On Mon, Aug 18, 2008 at 06:53:51PM -0700, Kevin Diggs wrote:
> Could someone ... anyone take a look at these kernel doc additions?
.....
>
> +/**
> + * complete: - signals a single thread waiting on this completion
> + * @x:  holds the state of this particular completion
> + *
> + * This will wake up a single thread waiting on this completion. If  
> multiple

Your mailer appears to be wrapping lines.

> + * threads are waiting ???
> + */
>  void complete(struct completion *x)
>  {
>         unsigned long flags;

complete() will only wake one waiting thread. If there are multiple
waiters, then further calls to complete() are required to wake them,
or a single call to complete_all() could be used.

>  EXPORT_SYMBOL(wait_for_completion);
>
> +/**
> + * wait_for_completion_timeout: - waits for completion of a task  
> (w/timeout)
> + * @x:  holds the state of this particular completion
> + * @timeout:  timeout value in jiffies
> + *
> + * This waits to be signaled for completion of a specific task. It is NOT
> + * interruptible. But there is a timeout in jiffies.

Doesn't read very well.

"This waits for either a completion of a specific task to be signalled
or for a defined length of time. It is not interruptible."

> +/**
> + * wait_for_completion_interruptible_timeout: - waits for completion  
> (w/(to,int
> r))
> + * @x:  holds the state of this particular completion
> + * @timeout:  timeout value in jiffies
> + *
> + * This waits to be signaled for completion of a specific task. It is
> + * interruptible. And there is a timeout in jiffies.
> + */

Same as for wait_for_completion_timeout().

> +/**
> + * wait_for_completion_killable: - waits for completion of a task  
> (killable)
> + * @x:  holds the state of this particular completion
> + *
> + * This waits to be signaled for completion of a specific task. It is
> + * killable (???).
> + */

Killable means that a kill signal will interrupt the wait, but not
all signals will. Typically used in places where you want a user
ctrl-c or a kill command to succeed but don't want any other signal
to interrupt the completion.

Cheers,

Dave.
-- 
Dave Chinner
david@fromorbit.com