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

[Boqun Feng <boqun.feng@gmail.com>]

On Tue, Oct 19, 2021 at 07:47:56AM -1000, Tejun Heo wrote:
> On Mon, Oct 18, 2021 at 09:31:17AM +0800, Boqun Feng wrote:
> > +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.
> 
> Maybe phrasing it so that the above are the conditions defining a work item
> to be the same instance would be clearer?
> 

Hmm.. that would mean queue_work_on() may change the work item to
another instance? For example:

	struct work_struct w;

	INIT_WORK_ONSTACK(w, some_f);

	queue_work_on(&w, system_wq, 1); // queue a work and create
					 // an instance

	queue_work_on(&w, system_long_wq, 2); // queue the same work
					      // item but it means
					      // changing it to another
					      // instance.

Looks a little counter-intuitive to me, but let me try (combined with
Matthew's suggestion)

<in Guidelines section>

* A work item instance will not be processed by multiple workers at the
  same time, i.e. it's non-reentrant, so requeuing the same instance of
  a work item is safe and not racy.  Operations considered as changing
  the work item to a different instance are: 1) change the work
  function, 2) queue the work item to a different workqueue, or 3)
  reinitiate the work item.  The non-reentrance guarantee doesn't hold
  for different work item instances.

Regards,
Boqun

> Thanks.
> 
> -- 
> tejun