From f9eaaa82b474350aa8436d15a7ae150a3c8b9d5c Mon Sep 17 00:00:00 2001 From: Boqun Feng Date: Fri, 22 Oct 2021 08:42:08 +0800 Subject: workqueue: doc: Call out the non-reentrance conditions 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 Suggested-by: Tejun Heo Signed-off-by: Boqun Feng Signed-off-by: Tejun Heo --- Documentation/core-api/workqueue.rst | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) (limited to 'Documentation/core-api') 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 ====================================== -- cgit