Date: Tue, 19 Aug 2008 12:41:25 +1000
From: Dave Chinner <david@fromorbit.com>
To: Kevin Diggs <kevdig@hypersurf.com>
Cc: linux-kernel@vger.kernel.org
Subject: Re: [Fwd: Corrections please ...]
Message-ID: <20080819024125.GM19760@disturbed>
Mail-Followup-To: Kevin Diggs <kevdig@hypersurf.com>,
	linux-kernel@vger.kernel.org
References: <48AA27AF.9070407@hypersurf.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <48AA27AF.9070407@hypersurf.com>
User-Agent: Mutt/1.5.18 (2008-05-17)
Sender: linux-kernel-owner@vger.kernel.org
Content-Length: 2404
Lines: 77

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
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/