* [PATCH v2] workqueue: doc: Call out the non-reentrance conditions
@ 2021-10-22 0:42 Boqun Feng
2021-10-25 17:20 ` Tejun Heo
0 siblings, 1 reply; 2+ messages in thread
From: Boqun Feng @ 2021-10-22 0:42 UTC (permalink / raw)
To: linux-kernel, linux-doc
Cc: Tejun Heo, Lai Jiangshan, Paul E . McKenney, Thomas Gleixner,
Peter Zijlstra, Frederic Weisbecker, Jonathan Corbet, Boqun Feng,
Matthew Wilcox
The current doc of workqueue API suggests that work items are
non-reentrant: any work item is guaranteed to be executed by at most one
worker system-wide at any given time. However this is not true, the
following case can cause a work item W executed by two workers at
the same time:
queue_work_on(0, WQ1, W);
// after a worker picks up W and clear the pending bit
queue_work_on(1, WQ2, W);
// workers on CPU0 and CPU1 will execute W in the same time.
, which means the non-reentrance of a work item is conditional, and
Lai Jiangshan provided a nice summary[1] of the conditions, therefore
use it to describe a work item instance and improve the doc.
[1]: https://lore.kernel.org/lkml/CAJhGHyDudet_xyNk=8xnuO2==o-u06s0E0GZVP4Q67nmQ84Ceg@mail.gmail.com/
Suggested-by: Matthew Wilcox <willy@infradead.org>
Suggested-by: Tejun Heo <tj@kernel.org>
Signed-off-by: Boqun Feng <boqun.feng@gmail.com>
---
v1 -> v2:
* Apply the suggestion from Matthew and Tejun
[v1]: https://lore.kernel.org/lkml/20211018013117.256284-1-boqun.feng@gmail.com/
Documentation/core-api/workqueue.rst | 21 +++++++++++++++++----
1 file changed, 17 insertions(+), 4 deletions(-)
diff --git a/Documentation/core-api/workqueue.rst b/Documentation/core-api/workqueue.rst
index 541d31de8926..3b22ed137662 100644
--- a/Documentation/core-api/workqueue.rst
+++ b/Documentation/core-api/workqueue.rst
@@ -216,10 +216,6 @@ resources, scheduled and executed.
This flag is meaningless for unbound wq.
-Note that the flag ``WQ_NON_REENTRANT`` no longer exists as all
-workqueues are now non-reentrant - any work item is guaranteed to be
-executed by at most one worker system-wide at any given time.
-
``max_active``
--------------
@@ -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.
+
Kernel Inline Documentations Reference
======================================
--
2.33.0
^ permalink raw reply related [flat|nested] 2+ messages in thread
* Re: [PATCH v2] workqueue: doc: Call out the non-reentrance conditions
2021-10-22 0:42 [PATCH v2] workqueue: doc: Call out the non-reentrance conditions Boqun Feng
@ 2021-10-25 17:20 ` Tejun Heo
0 siblings, 0 replies; 2+ messages in thread
From: Tejun Heo @ 2021-10-25 17:20 UTC (permalink / raw)
To: Boqun Feng
Cc: linux-kernel, linux-doc, Lai Jiangshan, Paul E . McKenney,
Thomas Gleixner, Peter Zijlstra, Frederic Weisbecker,
Jonathan Corbet, Matthew Wilcox
On Fri, Oct 22, 2021 at 08:42:08AM +0800, Boqun Feng wrote:
> The current doc of workqueue API suggests that work items are
> non-reentrant: any work item is guaranteed to be executed by at most one
> worker system-wide at any given time. However this is not true, the
> following case can cause a work item W executed by two workers at
> the same time:
>
> queue_work_on(0, WQ1, W);
> // after a worker picks up W and clear the pending bit
> queue_work_on(1, WQ2, W);
> // workers on CPU0 and CPU1 will execute W in the same time.
>
> , which means the non-reentrance of a work item is conditional, and
> Lai Jiangshan provided a nice summary[1] of the conditions, therefore
> use it to describe a work item instance and improve the doc.
>
> [1]: https://lore.kernel.org/lkml/CAJhGHyDudet_xyNk=8xnuO2==o-u06s0E0GZVP4Q67nmQ84Ceg@mail.gmail.com/
>
> Suggested-by: Matthew Wilcox <willy@infradead.org>
> Suggested-by: Tejun Heo <tj@kernel.org>
> Signed-off-by: Boqun Feng <boqun.feng@gmail.com>
Applied to wq/for-5.16.
Thanks.
--
tejun
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2021-10-25 17:20 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-10-22 0:42 [PATCH v2] workqueue: doc: Call out the non-reentrance conditions Boqun Feng
2021-10-25 17:20 ` Tejun Heo
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.