Re: [PATCH] workqueue: doc: Call out the non-reentrance conditions

[Matthew Wilcox <willy@infradead.org>]

On Mon, Oct 18, 2021 at 11:19:14AM +0800, Boqun Feng wrote:
> On Mon, Oct 18, 2021 at 03:17:53AM +0100, Matthew Wilcox wrote:
> > On Mon, Oct 18, 2021 at 09:31:17AM +0800, Boqun Feng wrote:
> > > @@ -391,6 +387,23 @@ the stack trace of the offending worker thread. ::
> > >  The work item's function should be trivially visible in the stack
> > >  trace.
> > >  
> > > +Non-reentrance Conditions
> > > +=========================
> > > +
> > > +Workqueue guarantees that a work item cannot be re-entrant if the following
> > > +conditions hold after a work item gets queued:
> > > +
> > > +        1. The work function hasn't been changed.
> > > +        2. No one queues the work item to another workqueue.
> > > +        3. The work item hasn't been reinitiated.
> > > +
> > > +In other words, if the above conditions hold, the work item is guaranteed to be
> > > +executed by at most one worker system-wide at any given time.
> > > +
> > > +Note that requeuing the work item (to the same queue) in the self function
> > > +doesn't break these conditions, so it's safe to do. Otherwise, caution is
> > > +required when breaking the conditions inside a work function.
> > > +
> > 
> > I'd like to suggest that this be added to the Guidelines section
> 
> Good idea, Guidelines section is a better place to put these, since it's
> for users.
> 
> > instead:
> > 
> > * A work item will not normally be processed on multiple CPUs at the
> 
> Precisely speaking, it should be "by mutliple workers" instead of "on
> multiple CPUs", because two workers of tw unbound workqueue may process
> the same work item on the same CPU, and that's problematic since
> processing work is preemptible.
> 
> >   same time.  It can happen if the work function is changed, the work
> >   item is queued to multiple queues or the work function is
> >   reinitialised after being queued.
> 
> I end up with something like below, I still want to keep the keyword
> "reentrant" for searching, because sometimes one may forget this
> particular aspect after reading the whole doc for a while, the keyword
> can help locate the lines faster (Ok, the fact is that "one" was me
> ;-)).
> 
> * A work item will not normally be processed by multiple workers at the
>   same time, i.e. it's non-reentrant.  However it can happen if the work
>   function is changed, the work item is queued to multiple queues or the
>   work item is reinitialised after being queued.
> 
> Thoughts? Thank for the suggestion!

Looks good to me!