[Fwd: Corrections please ...]
Could someone ... anyone take a look at these kernel doc additions?
Thanks!
kevin
Could I get any needed corrections on this. Especially on the "???"
[kevdig@PowerMac8600B linux-2.6.26]$ diff -U3 include/linux/completion.{h.orig,h}|more
linux/completion.h 2008-08-18 13:00:23.000000000 -0700 renamed from linux/completion.h.orig 2008-08-13 00:56:52.000000000 -0700 +17 -0
@@ -10,6 +10,16 @@ #include <linux/wait.h> +/** + * struct completion - structure used to maintain state for a "completion" + * @done: counting variable used to signal completion + * @wait: internal wait queue head; used for locking and synchronization + * + * This is the structure used to maintain the state for a "completion". See + * also: complete(), wait_for_completion() (and friends _timeout, + * _interruptible, _interruptible_timeout, and _killable), init_completion(), + * and macros DECLARE_COMPLETION() and INIT_COMPLETION(). + */ struct completion { unsigned int done; wait_queue_head_t wait;
@@ -36,6 +46,13 @@ # define DECLARE_COMPLETION_ONSTACK(work) DECLARE_COMPLETION(work) #endif +/** + * init_completion: - Initialize a dynamically allocated completion + * @x: completion structure that is to be initialized + * + * This inline function will initialize a dynamically created completion + * structure. + */ static inline void init_completion(struct completion *x) { x->done = 0;
sched.c 2008-08-18 13:31:03.000000000 -0700 renamed from sched.c.orig 2008-08-13 02:22:42.000000000 -0700 +35 -0
@@ -4363,6 +4363,13 @@ } EXPORT_SYMBOL_GPL(__wake_up_sync); /* For internal use only */ +/** + * 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 + * threads are waiting ??? + */ void complete(struct completion *x) { unsigned long flags;
@@ -4374,6 +4381,12 @@ } EXPORT_SYMBOL(complete); +/** + * complete_all: - signals all threads waiting on this completion + * @x: holds the state of this particular completion + * + * This will wake up all threads waiting on this particular completion event. + */ void complete_all(struct completion *x) { unsigned long flags;
@@ -4425,12 +4438,27 @@ return timeout; } +/** + * wait_for_completion: - waits for completion of a task + * @x: holds the state of this particular completion + * + * This waits to be signaled for completion of a specific task. It is NOT + * interruptible and there is no timeout. + */ void __sched wait_for_completion(struct completion *x) { wait_for_common(x, MAX_SCHEDULE_TIMEOUT, TASK_UNINTERRUPTIBLE); } 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. + */ unsigned long __sched wait_for_completion_timeout(struct completion *x, unsigned long timeout) {
@@ -4438,6 +4466,13 @@ } EXPORT_SYMBOL(wait_for_completion_timeout); +/** + * wait_for_completion_interruptible: - waits for completion of a task (w/intr) + * @x: holds the state of this particular completion + * + * This waits to be signaled for completion of a specific task. It is + * interruptible. + */ int __sched wait_for_completion_interruptible(struct completion *x) { long t = wait_for_common(x, MAX_SCHEDULE_TIMEOUT,
TASK_INTERRUPTIBLE);
@@ -4447,6 +4482,14 @@
} EXPORT_SYMBOL(wait_for_completion_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.
+ */
unsigned long __sched wait_for_completion_interruptible_timeout(struct completion *x,
unsigned long timeout)
@@ -4455,6 +4498,13 @@
}
EXPORT_SYMBOL(wait_for_completion_interruptible_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 (???).
+ */
int __sched wait_for_completion_killable(struct completion *x)
{
long t = wait_for_common(x, MAX_SCHEDULE_TIMEOUT, TASK_KILLABLE);Quoted 1 line · Kevin Diggs
Could someone ... anyone take a look at these kernel doc additions?
.....
Quoted 7 lines
+/**
+ * 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.
Quoted 5 lines
+ * threads are waiting ???
+ */
voidcomplete(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.
Quoted 10 lines
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."
Quoted 10 lines
+/**
+ *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().
Quoted 8 lines
+/**
+ *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.
Signature · 2 lines
Dave Chinner [email protected]
Quoted 24 lines · Dave Chinner
Quoted 1 line · Kevin Diggs
Could someone ... anyone take a look at these kernel doc additions?
.....
Quoted 6 lines
+/**
+ * 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 multipleYour mailer appears to be wrapping lines.
Quoted 5 lines
+ * threads are waiting ???
+ */
voidcomplete(struct completion *x){ unsigned long flags;
Quoted 8 lines
complete()will only wake one waiting thread. If there are multiple waiters, then further calls tocomplete()are required to wake them, or a single call tocomplete_all()could be used.Quoted 3 lines
EXPORT_SYMBOL(wait_for_completion);+/**
Take 2 ...
Files attached this time ...
kevin
linux/completion.h renamed from linux/completion.h.orig +17 -0
@@ -10,6 +10,16 @@#include <linux/wait.h> +/** +* struct completion - structure used to maintain state for a "completion" +* @done: counting variable used to signal completion +* @wait: internal wait queue head; used for locking and synchronization +* +* This is the structure used to maintain the state for a "completion". See +* also: complete(), wait_for_completion() (and friends _timeout, +* _interruptible, _interruptible_timeout, and _killable), init_completion(), +* and macros DECLARE_COMPLETION() and INIT_COMPLETION(). +*/ struct completion {unsigned int done;wait_queue_head_t wait;
@@ -36,6 +46,13 @@# define DECLARE_COMPLETION_ONSTACK (work) DECLARE_COMPLETION(work)#endif +/** +* init_completion: - Initialize a dynamically allocated completion +* @x: completion structure that is to be initialized +* +* This inline function will initialize a dynamically created completion +* structure. +*/ static inline void init_completion (struct completion *x) { x->done =0 ;
sched.c renamed from sched.c.orig +54 -0
96 lines not on this page · raw message
Quoted 1 line · Kevin Diggs
Files attached this time ...
Alas several MUAs don't quote attachments in replies. Hence the optimum would be if you use a MUA which allows to insert text files without whitespace change.
Also, when you respond on LKML, always use "reply to all" to keep previous responders in a thread Cc'd. This is necessary due to the high volume of LKML, and in order to not force people to subscribe to LKML.
Quoted 9 lines
linux/completion.h renamed from linux/completion.h.orig +3
-0@@ -10,6 +10,16 @@#include <linux/wait.h> +/** +* struct completion - structure used to maintain state for a "completion" +* @done: counting variable used to signal completion
linux/completion.h line 25
Quoted 10 lines
linux/completion.h renamed from linux/completion.h.orig +7
-0+* @wait: internal wait queue head; used for locking and synchronization +* +* This is the structure used to maintain the state for a "completion". See +* also: complete(), wait_for_completion() (and friends _timeout, +* _interruptible, _interruptible_timeout, and _killable), init_completion(), +* and macros DECLARE_COMPLETION() and INIT_COMPLETION(). +*/ struct completion {unsigned int done;wait_queue_head_t wait;
.done and .wait are not public AFAIU and should therefore not be documented as an API.
Quoted 4 lines
linux/completion.h renamed from linux/completion.h.orig +0
-0@@ -36,6 +46,13 @@# define DECLARE_COMPLETION_ONSTACK (work) DECLARE_COMPLETION(work)#endif
linux/completion.h line 58
Quoted 10 lines
linux/completion.h renamed from linux/completion.h.orig +7
-0+/** +* init_completion: - Initialize a dynamically allocated completion +* @x: completion structure that is to be initialized +* +* This inline function will initialize a dynamically created completion +* structure. +*/ static inline void init_completion (struct completion *x) { x->done =0 ;
The last sentence is redundant and should be omitted.
Signature · 3 lines
Stefan Richter -=====-==--- =--- =--== http://arcgraph.de/sr/
Quoted 16 lines · Kevin Diggs
Quoted 15 lines · Dave Chinner
Quoted 1 line · Kevin Diggs
Could someone ... anyone take a look at these kernel doc additions?
.....
Quoted 6 lines
+/**
+ * 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 multipleYour mailer appears to be wrapping lines.
Quoted 5 lines
+ * threads are waiting ???
+ */
voidcomplete(struct completion *x){ unsigned long flags;
Quoted 8 lines
Quoted 6 lines
complete()will only wake one waiting thread. If there are multiple waiters, then further calls tocomplete()are required to wake them, or a single call tocomplete_all()could be used.Quoted 3 lines
EXPORT_SYMBOL(wait_for_completion);+/**
Take 2 ...
You might want to read Documentation/SubmittingPatches. (Especially points 2, 7, 11 and 12)
Marcin