Re: [PATCH] Documentation: Remove misleading examples of the barriers in wake_*()

[Peter Zijlstra <peterz@infradead.org>]

On Mon, Oct 12, 2015 at 09:09:24PM +0800, Boqun Feng wrote:
> On Mon, Oct 12, 2015 at 01:54:38PM +0200, Peter Zijlstra wrote:
> > On Mon, Oct 12, 2015 at 05:06:36PM +0800, Boqun Feng wrote:
> > > Understood.
> > > 
> > > But, IMO, the position of this section is already misleading:
> > > 
> > > (*) Implicit kernel memory barriers.
> > >      - Locking functions.
> > >      - Interrupt disabling functions.
> > >    ->- Sleep and wake-up functions.<-
> > >      - Miscellaneous functions.
> > > 
> > > I read it as that sleep and wake-up functions provide some kernel memory
> > > barriers which we can use *externally*(outside sleep/wakeup themselves).
> > 
> > I think it is useful to state that the primitives handle the ordering
> > between the waker and wakee wrt the 'blocking' state.
> > 
> 
> I agree that's useful, however, the 'blocking' state is something
> internal for sleep and wakeup, right? 

Not entirely; its also the @cond thing in wait queues. IE:

	for (;;)
		set_current_state(TASK_INTERRUPTIBLE);
		if (@cond)
			break;
		schedule();
	}
	__set_current_state(TASK_RUNNING);

vs.

	@cond = true;
	wake_up_process(p);


So we guarantee that 'p' will see the @cond stores IF it does the
wakeup. (If it does not, ie. 'p' wasn't sleeping, any guarantee is out
the window).

> Not sure whether the users of
> wake_up() and wait_event() will care much about this or they need to
> understand that detailedly to use wake_up() and wait_event() correctly.

I think its mostly natural; but it explains why you don't have to do:

	wait_event(wq, @cond);

vs.

	@cond = true;
	smp_wmb();
	wake_up(wq);

(or worse...)


> > But I've not put much thought into wording. I wanted to finish process
> > order 'comment' patch first.
> 
> Of course. Actually your 'comment' patch is the reason why I think this
> section may be removed.

Yes, that is another option, referring to the comment, once that's
sorted.