diff mbox series

docs/completion.txt: Fix a couple of punctuation nits

Message ID 1539183392-239389-1-git-send-email-john.garry@huawei.com
State Accepted
Commit 7b6abce7e1e69b6d8dc5d40a8cb9ddaeb400427c
Headers show
Series docs/completion.txt: Fix a couple of punctuation nits | expand

Commit Message

John Garry Oct. 10, 2018, 2:56 p.m. UTC
This patch fixes a couple of punctuation nits which can make the document
more correct and readable.

Also missing "()" are added to some function references for consistency.

Signed-off-by: John Garry <john.garry@huawei.com>


-- 
1.9.1

Comments

Randy Dunlap Oct. 10, 2018, 3:47 p.m. UTC | #1
On 10/10/18 7:56 AM, John Garry wrote:
> This patch fixes a couple of punctuation nits which can make the document

> more correct and readable.

> 

> Also missing "()" are added to some function references for consistency.

> 

> Signed-off-by: John Garry <john.garry@huawei.com>


Acked-by: Randy Dunlap <rdunlap@infradead.org>


thanks,
-- 
~Randy
Matthew Wilcox Oct. 11, 2018, 3:29 p.m. UTC | #2
On Wed, Oct 10, 2018 at 10:56:32PM +0800, John Garry wrote:
> This patch fixes a couple of punctuation nits which can make the document

> more correct and readable.

> 

> Also missing "()" are added to some function references for consistency.


While there's nothing wrong here, any chance you want to try converting
it to .rst and adding it to the overall index?  It looks a lot like
rst already.
Peter Zijlstra Oct. 11, 2018, 3:41 p.m. UTC | #3
On Thu, Oct 11, 2018 at 08:29:10AM -0700, Matthew Wilcox wrote:
> On Wed, Oct 10, 2018 at 10:56:32PM +0800, John Garry wrote:

> > This patch fixes a couple of punctuation nits which can make the document

> > more correct and readable.

> > 

> > Also missing "()" are added to some function references for consistency.

> 

> While there's nothing wrong here, any chance you want to try converting

> it to .rst and adding it to the overall index?  It looks a lot like

> rst already.


I, on principle, will not touch rst files. They are inferior to txt files.
Jani Nikula Oct. 11, 2018, 6:46 p.m. UTC | #4
On Thu, 11 Oct 2018, Peter Zijlstra <peterz@infradead.org> wrote:
> On Thu, Oct 11, 2018 at 08:29:10AM -0700, Matthew Wilcox wrote:

>> On Wed, Oct 10, 2018 at 10:56:32PM +0800, John Garry wrote:

>> > This patch fixes a couple of punctuation nits which can make the document

>> > more correct and readable.

>> > 

>> > Also missing "()" are added to some function references for consistency.

>> 

>> While there's nothing wrong here, any chance you want to try converting

>> it to .rst and adding it to the overall index?  It looks a lot like

>> rst already.

>

> I, on principle, will not touch rst files. They are inferior to txt files.


$ git shortlog --author=Zijlstra  -- Documentation/scheduler/

It does not look like you touch txt files either.


BR,
Jani.

-- 
Jani Nikula, Intel Open Source Graphics Center
Ingo Molnar Oct. 11, 2018, 10:06 p.m. UTC | #5
hi Nicholas,

I was wondering about this paragraph:

> Using on-stack completions for code that calls any of the _timeout or

> _interruptible/_killable variants is not advisable as they will require

> additional synchronization to prevent the on-stack completion object in

> the timeout/signal cases from going out of scope. Consider using dynamically

> allocated completions when intending to use the _interruptible/_killable

> or _timeout variants of wait_for_completion().


What exact race related to _timeout()/_interruptible() waits and on-stack
completions were you trying to highlight here?

Is it the fact that if a signal is already pending for the current task,
that the _interruptible() variant might return prematurely, while any
kthread that has the completion pointer passed to it might still be using
it?

In that case the kthread should indeed be waited for.

How would a dynamically allocated completion object help in this case - or do
you mean a refcounted dynamic object?

A specific example might be useful here, instead of this rather vague,
generic description.

Thanks,

	Ingo
Peter Zijlstra Oct. 12, 2018, 9:32 a.m. UTC | #6
On Thu, Oct 11, 2018 at 09:46:56PM +0300, Jani Nikula wrote:
> On Thu, 11 Oct 2018, Peter Zijlstra <peterz@infradead.org> wrote:

> > On Thu, Oct 11, 2018 at 08:29:10AM -0700, Matthew Wilcox wrote:

> >> On Wed, Oct 10, 2018 at 10:56:32PM +0800, John Garry wrote:

> >> > This patch fixes a couple of punctuation nits which can make the document

> >> > more correct and readable.

> >> > 

> >> > Also missing "()" are added to some function references for consistency.

> >> 

> >> While there's nothing wrong here, any chance you want to try converting

> >> it to .rst and adding it to the overall index?  It looks a lot like

> >> rst already.

> >

> > I, on principle, will not touch rst files. They are inferior to txt files.

> 

> $ git shortlog --author=Zijlstra  -- Documentation/scheduler/

> 

> It does not look like you touch txt files either.


True; I prefer comments in the code. I did however write some text on
atomics the other day, see Documentation/atomic_{t,bitops}.txt.
Jonathan Corbet Oct. 12, 2018, 5:27 p.m. UTC | #7
On Wed, 10 Oct 2018 22:56:32 +0800
John Garry <john.garry@huawei.com> wrote:

> This patch fixes a couple of punctuation nits which can make the document

> more correct and readable.

> 

> Also missing "()" are added to some function references for consistency.

> 

> Signed-off-by: John Garry <john.garry@huawei.com>


Applied, thanks.

I agree with the suggestion to move it to RST - happily, it's already a
valid RST file, and would really only requires a few small tweaks.  Of
course, perhaps the existing RST-compatible markup already renders it
"inferior" :)

jon
diff mbox series

Patch

diff --git a/Documentation/scheduler/completion.txt b/Documentation/scheduler/completion.txt
index 656cf80..108bd0f 100644
--- a/Documentation/scheduler/completion.txt
+++ b/Documentation/scheduler/completion.txt
@@ -116,7 +116,7 @@  A typical usage scenario is:
 This is not implying any temporal order on wait_for_completion() and the
 call to complete() - if the call to complete() happened before the call
 to wait_for_completion() then the waiting side simply will continue
-immediately as all dependencies are satisfied if not it will block until
+immediately as all dependencies are satisfied; if not, it will block until
 completion is signaled by complete().
 
 Note that wait_for_completion() is calling spin_lock_irq()/spin_unlock_irq(),
@@ -131,7 +131,7 @@  wait_for_completion():
 The default behavior is to wait without a timeout and to mark the task as
 uninterruptible. wait_for_completion() and its variants are only safe
 in process context (as they can sleep) but not in atomic context,
-interrupt context, with disabled irqs. or preemption is disabled - see also
+interrupt context, with disabled irqs, or preemption is disabled - see also
 try_wait_for_completion() below for handling completion in atomic/interrupt
 context.
 
@@ -224,7 +224,7 @@  queue spinlock. Any such concurrent calls to complete() or complete_all()
 probably are a design bug.
 
 Signaling completion from hard-irq context is fine as it will appropriately
-lock with spin_lock_irqsave/spin_unlock_irqrestore and it will never sleep.
+lock with spin_lock_irqsave()/spin_unlock_irqrestore() and it will never sleep.
 
 
 try_wait_for_completion()/completion_done():