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

include/linux/completion.h+41−0

@@ -10,6 +10,18 @@ · 9 unmodified lines
10	10
11	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	25	struct completion {
14	26	unsigned int done;
15	27	wait_queue_head_t wait;
@@ -21,6 +33,14 @@ struct completion { · 5 unmodified lines
21	33	#define COMPLETION_INITIALIZER_ONSTACK(work) \
22	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	44	#define DECLARE_COMPLETION(work) \
25	45	struct completion work = COMPLETION_INITIALIZER(work)
26	46
@@ -29,6 +49,13 @@ struct completion { · 2 unmodified lines
29	49	* completions - so we use the _ONSTACK() variant for those that
30	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	59	#ifdef CONFIG_LOCKDEP
33	60	# define DECLARE_COMPLETION_ONSTACK(work) \
34	61	struct completion work = COMPLETION_INITIALIZER_ONSTACK(work)
@@ -36,6 +63,13 @@ struct completion { · 1 unmodified line
36	63	# define DECLARE_COMPLETION_ONSTACK(work) DECLARE_COMPLETION(work)
37	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	73	static inline void init_completion(struct completion *x)
40	74	{
41	75	x->done = 0;
@@ -55,6 +89,13 @@ extern bool completion_done(struct completion *x); · 13 unmodified lines
55	89	extern void complete(struct completion *);
56	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	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	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	4577	void complete(struct completion *x)
4569	4578	{
4570	4579	unsigned long flags;
@@ -4576,6 +4585,12 @@ void complete(struct completion *x) · 5 unmodified lines
4576	4585	}
4577	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	4594	void complete_all(struct completion *x)
4580	4595	{
4581	4596	unsigned long flags;
@@ -4624,12 +4639,31 @@ wait_for_common(struct completion *x, long timeout, int state) · 42 unmodified lines
4624	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	4652	void __sched wait_for_completion(struct completion *x)
4628	4653	{
4629	4654	wait_for_common(x, MAX_SCHEDULE_TIMEOUT, TASK_UNINTERRUPTIBLE);
4630	4655	}
4631	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	4667	unsigned long __sched
4634	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	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	4681	int __sched wait_for_completion_interruptible(struct completion *x)
4641	4682	{
4642	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	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	4698	unsigned long __sched
4650	4699	wait_for_completion_interruptible_timeout(struct completion *x,
4651	4700	unsigned long timeout)
@@ -4654,6 +4703,13 @@ wait_for_completion_interruptible_timeout(struct completion *x, · 2 unmodified lines
4654	4703	}
4655	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	4713	int __sched wait_for_completion_killable(struct completion *x)
4658	4714	{
4659	4715	long t = wait_for_common(x, MAX_SCHEDULE_TIMEOUT, TASK_KILLABLE);