sched: add kernel doc for the completion, fix kernel-doc-nano-HOWTO.txt

This patch adds kernel doc for the completion feature. An error in the split-man.pl PERL snippet in kernel-doc-nano-HOWTO.txt is also fixed.

Kevin Diggs committed 18 years ago

Commit 65eb3dc1 parent 3cf430b3 files · +99 −2Browse files

Unified · Split

3 files

Documentation/kernel-doc-nano-HOWTO.txt +2 −2
include/linux/completion.h +41 −0
kernel/sched.c +56 −0

Documentation/kernel-doc-nano-HOWTO.txt+2−2

@@ -168,10 +168,10 @@ if ($#ARGV < 0) { · 167 unmodified lines
168	mkdir $ARGV[0],0777;	168	mkdir $ARGV[0],0777;
169	$state = 0;	169	$state = 0;
170	while (<STDIN>) {	170	while (<STDIN>) {
171	if (/^\.TH \"[^\"]\" 4 \"([^\"])\"/) {	171	if (/^\.TH \"[^\"]\" 9 \"([^\"])\"/) {
172	if ($state == 1) { close OUT }	172	if ($state == 1) { close OUT }
173	$state = 1;	173	$state = 1;
174	$fn = "$ARGV[0]/$1.4";	174	$fn = "$ARGV[0]/$1.9";
175	print STDERR "Creating $fn\n";	175	print STDERR "Creating $fn\n";
176	open OUT, ">$fn" or die "can't open $fn: $!\n";	176	open OUT, ">$fn" or die "can't open $fn: $!\n";
177	print OUT $_;	177	print OUT $_;

include/linux/completion.h+41−0

@@ -10,6 +10,18 @@ · 9 unmodified lines
10		10
11	#include <linux/wait.h>	11	#include <linux/wait.h>
12		12
		13	/**
		14	* struct completion - structure used to maintain state for a "completion"
		15	*
		16	* This is the opaque structure used to maintain the state for a "completion".
		17	* Completions currently use a FIFO to queue threads that have to wait for
		18	* the "completion" event.
		19	*
		20	* See also: complete(), wait_for_completion() (and friends _timeout,
		21	* _interruptible, _interruptible_timeout, and _killable), init_completion(),
		22	* and macros DECLARE_COMPLETION(), DECLARE_COMPLETION_ONSTACK(), and
		23	* INIT_COMPLETION().
		24	*/
13	struct completion {	25	struct completion {
14	unsigned int done;	26	unsigned int done;
15	wait_queue_head_t wait;	27	wait_queue_head_t wait;
@@ -21,6 +33,14 @@ struct completion { · 5 unmodified lines
21	#define COMPLETION_INITIALIZER_ONSTACK(work) \	33	#define COMPLETION_INITIALIZER_ONSTACK(work) \
22	({ init_completion(&work); work; })	34	({ init_completion(&work); work; })
23		35
		36	/**
		37	* DECLARE_COMPLETION: - declare and initialize a completion structure
		38	* @work: identifier for the completion structure
		39	*
		40	* This macro declares and initializes a completion structure. Generally used
		41	* for static declarations. You should use the _ONSTACK variant for automatic
		42	* variables.
		43	*/
24	#define DECLARE_COMPLETION(work) \	44	#define DECLARE_COMPLETION(work) \
25	struct completion work = COMPLETION_INITIALIZER(work)	45	struct completion work = COMPLETION_INITIALIZER(work)
26		46
@@ -29,6 +49,13 @@ struct completion { · 2 unmodified lines
29	* completions - so we use the _ONSTACK() variant for those that	49	* completions - so we use the _ONSTACK() variant for those that
30	* are on the kernel stack:	50	* are on the kernel stack:
31	*/	51	*/
		52	/**
		53	* DECLARE_COMPLETION_ONSTACK: - declare and initialize a completion structure
		54	* @work: identifier for the completion structure
		55	*
		56	* This macro declares and initializes a completion structure on the kernel
		57	* stack.
		58	*/
32	#ifdef CONFIG_LOCKDEP	59	#ifdef CONFIG_LOCKDEP
33	# define DECLARE_COMPLETION_ONSTACK(work) \	60	# define DECLARE_COMPLETION_ONSTACK(work) \
34	struct completion work = COMPLETION_INITIALIZER_ONSTACK(work)	61	struct completion work = COMPLETION_INITIALIZER_ONSTACK(work)
@@ -36,6 +63,13 @@ struct completion { · 1 unmodified line
36	# define DECLARE_COMPLETION_ONSTACK(work) DECLARE_COMPLETION(work)	63	# define DECLARE_COMPLETION_ONSTACK(work) DECLARE_COMPLETION(work)
37	#endif	64	#endif
38		65
		66	/**
		67	* init_completion: - Initialize a dynamically allocated completion
		68	* @x: completion structure that is to be initialized
		69	*
		70	* This inline function will initialize a dynamically created completion
		71	* structure.
		72	*/
39	static inline void init_completion(struct completion *x)	73	static inline void init_completion(struct completion *x)
40	{	74	{
41	x->done = 0;	75	x->done = 0;
@@ -55,6 +89,13 @@ extern bool completion_done(struct completion *x); · 13 unmodified lines
55	extern void complete(struct completion *);	89	extern void complete(struct completion *);
56	extern void complete_all(struct completion *);	90	extern void complete_all(struct completion *);
57		91
		92	/**
		93	* INIT_COMPLETION: - reinitialize a completion structure
		94	* @x: completion structure to be reinitialized
		95	*
		96	* This macro should be used to reinitialize a completion structure so it can
		97	* be reused. This is especially important after complete_all() is used.
		98	*/
58	#define INIT_COMPLETION(x) ((x).done = 0)	99	#define INIT_COMPLETION(x) ((x).done = 0)
59		100
60		101

kernel/sched.c+56−0

@@ -4565,6 +4565,15 @@ __wake_up_sync(wait_queue_head_t *q, unsigned int mode, int nr_exclusive) · 4564 unmodified lines
4565	}	4565	}
4566	EXPORT_SYMBOL_GPL(__wake_up_sync); /* For internal use only */	4566	EXPORT_SYMBOL_GPL(__wake_up_sync); /* For internal use only */
4567		4567
		4568	/**
		4569	* complete: - signals a single thread waiting on this completion
		4570	* @x: holds the state of this particular completion
		4571	*
		4572	* This will wake up a single thread waiting on this completion. Threads will be
		4573	* awakened in the same order in which they were queued.
		4574	*
		4575	* See also complete_all(), wait_for_completion() and related routines.
		4576	*/
4568	void complete(struct completion *x)	4577	void complete(struct completion *x)
4569	{	4578	{
4570	unsigned long flags;	4579	unsigned long flags;
@@ -4576,6 +4585,12 @@ void complete(struct completion *x) · 5 unmodified lines
4576	}	4585	}
4577	EXPORT_SYMBOL(complete);	4586	EXPORT_SYMBOL(complete);
4578		4587
		4588	/**
		4589	* complete_all: - signals all threads waiting on this completion
		4590	* @x: holds the state of this particular completion
		4591	*
		4592	* This will wake up all threads waiting on this particular completion event.
		4593	*/
4579	void complete_all(struct completion *x)	4594	void complete_all(struct completion *x)
4580	{	4595	{
4581	unsigned long flags;	4596	unsigned long flags;
@@ -4624,12 +4639,31 @@ wait_for_common(struct completion *x, long timeout, int state) · 42 unmodified lines
4624	return timeout;	4639	return timeout;
4625	}	4640	}
4626		4641
		4642	/**
		4643	* wait_for_completion: - waits for completion of a task
		4644	* @x: holds the state of this particular completion
		4645	*
		4646	* This waits to be signaled for completion of a specific task. It is NOT
		4647	* interruptible and there is no timeout.
		4648	*
		4649	* See also similar routines (i.e. wait_for_completion_timeout()) with timeout
		4650	* and interrupt capability. Also see complete().
		4651	*/
4627	void __sched wait_for_completion(struct completion *x)	4652	void __sched wait_for_completion(struct completion *x)
4628	{	4653	{
4629	wait_for_common(x, MAX_SCHEDULE_TIMEOUT, TASK_UNINTERRUPTIBLE);	4654	wait_for_common(x, MAX_SCHEDULE_TIMEOUT, TASK_UNINTERRUPTIBLE);
4630	}	4655	}
4631	EXPORT_SYMBOL(wait_for_completion);	4656	EXPORT_SYMBOL(wait_for_completion);
4632		4657
		4658	/**
		4659	* wait_for_completion_timeout: - waits for completion of a task (w/timeout)
		4660	* @x: holds the state of this particular completion
		4661	* @timeout: timeout value in jiffies
		4662	*
		4663	* This waits for either a completion of a specific task to be signaled or for a
		4664	* specified timeout to expire. The timeout is in jiffies. It is not
		4665	* interruptible.
		4666	*/
4633	unsigned long __sched	4667	unsigned long __sched
4634	wait_for_completion_timeout(struct completion *x, unsigned long timeout)	4668	wait_for_completion_timeout(struct completion *x, unsigned long timeout)
4635	{	4669	{
@@ -4637,6 +4671,13 @@ wait_for_completion_timeout(struct completion *x, unsigned long timeout) · 1 unmodified line
4637	}	4671	}
4638	EXPORT_SYMBOL(wait_for_completion_timeout);	4672	EXPORT_SYMBOL(wait_for_completion_timeout);
4639		4673
		4674	/**
		4675	* wait_for_completion_interruptible: - waits for completion of a task (w/intr)
		4676	* @x: holds the state of this particular completion
		4677	*
		4678	* This waits for completion of a specific task to be signaled. It is
		4679	* interruptible.
		4680	*/
4640	int __sched wait_for_completion_interruptible(struct completion *x)	4681	int __sched wait_for_completion_interruptible(struct completion *x)
4641	{	4682	{
4642	long t = wait_for_common(x, MAX_SCHEDULE_TIMEOUT, TASK_INTERRUPTIBLE);	4683	long t = wait_for_common(x, MAX_SCHEDULE_TIMEOUT, TASK_INTERRUPTIBLE);
@@ -4646,6 +4687,14 @@ int __sched wait_for_completion_interruptible(struct completion *x) · 3 unmodified lines
4646	}	4687	}
4647	EXPORT_SYMBOL(wait_for_completion_interruptible);	4688	EXPORT_SYMBOL(wait_for_completion_interruptible);
4648		4689
		4690	/**
		4691	* wait_for_completion_interruptible_timeout: - waits for completion (w/(to,intr))
		4692	* @x: holds the state of this particular completion
		4693	* @timeout: timeout value in jiffies
		4694	*
		4695	* This waits for either a completion of a specific task to be signaled or for a
		4696	* specified timeout to expire. It is interruptible. The timeout is in jiffies.
		4697	*/
4649	unsigned long __sched	4698	unsigned long __sched
4650	wait_for_completion_interruptible_timeout(struct completion *x,	4699	wait_for_completion_interruptible_timeout(struct completion *x,
4651	unsigned long timeout)	4700	unsigned long timeout)
@@ -4654,6 +4703,13 @@ wait_for_completion_interruptible_timeout(struct completion *x, · 2 unmodified lines
4654	}	4703	}
4655	EXPORT_SYMBOL(wait_for_completion_interruptible_timeout);	4704	EXPORT_SYMBOL(wait_for_completion_interruptible_timeout);
4656		4705
		4706	/**
		4707	* wait_for_completion_killable: - waits for completion of a task (killable)
		4708	* @x: holds the state of this particular completion
		4709	*
		4710	* This waits to be signaled for completion of a specific task. It can be
		4711	* interrupted by a kill signal.
		4712	*/
4657	int __sched wait_for_completion_killable(struct completion *x)	4713	int __sched wait_for_completion_killable(struct completion *x)
4658	{	4714	{
4659	long t = wait_for_common(x, MAX_SCHEDULE_TIMEOUT, TASK_KILLABLE);	4715	long t = wait_for_common(x, MAX_SCHEDULE_TIMEOUT, TASK_KILLABLE);