From: Alice Ryhl <aliceryhl@google.com>
To: Tejun Heo <tj@kernel.org>, Lai Jiangshan <jiangshanlai@gmail.com>,
Jonathan Corbet <corbet@lwn.net>
Cc: "Boqun Feng" <boqun@kernel.org>,
"Miguel Ojeda" <ojeda@kernel.org>,
"Danilo Krummrich" <dakr@kernel.org>,
"Philipp Stanner" <phasta@kernel.org>,
"Matthew Brost" <matthew.brost@intel.com>,
"Christian König" <ckoenig.leichtzumerken@gmail.com>,
"Thomas Hellström" <thomas.hellstrom@linux.intel.com>,
"Rodrigo Vivi" <rodrigo.vivi@intel.com>,
"Boris Brezillon" <boris.brezillon@collabora.com>,
"Steven Price" <steven.price@arm.com>,
"Liviu Dudau" <liviu.dudau@arm.com>,
"Onur Özkan" <work@onurozkan.dev>,
dri-devel@lists.freedesktop.org, intel-xe@lists.freedesktop.org,
rust-for-linux@vger.kernel.org, linux-doc@vger.kernel.org,
linux-kernel@vger.kernel.org, "Alice Ryhl" <aliceryhl@google.com>
Subject: [PATCH 2/2] workqueue: doc: clarify cancel_work_sync() cross-workqueue behavior
Date: Wed, 18 Nov 2026 17:09:52 +0000 [thread overview]
Message-ID: <20261118-ordered-wq-cancel-v1-2-916e01f9affe@google.com> (raw)
In-Reply-To: <20261118-ordered-wq-cancel-v1-0-916e01f9affe@google.com>
The kernel-doc comment for cancel_work_sync() claims that it waits for
@work to finish even if @work "migrates to another workqueue". However,
this has not been true since commit 606a5020b9bd ("workqueue: gut
flush[_delayed]_work_sync()") replaced the all-pools scan with
start_flush_work(). Consider the following scenario:
1. @work starts executing on wq A (pool A).
2. While @work is still executing on pool A, it is queued onto a
different workqueue wq B (backed by pool B). Because __queue_work()
only redirects to last_pool when re-queueing onto the same workqueue,
@work is queued on pool B (where it may even start executing
concurrently with pool A) and work->data is overwritten with wq B's
pwq / pool B.
3. flush_work(), cancel_work_sync(), or disable_work_sync() is called on
@work.
4. start_flush_work() only inspects the single pool recorded in
work->data (pool B) and returns once @work is no longer pending or
executing on pool B, while @work is still executing on pool A.
Queueing an in-flight work item onto another workqueue already violates
the documented non-reentrance conditions in
Documentation/core-api/workqueue.rst. Thus, update the kernel-doc
comments for flush_work(), cancel_work_sync(), and disable_work_sync()
along with workqueue.rst to stop claiming that cross-workqueue migration
is supported, and link directly to the non-reentrance conditions
section.
Fixes: 606a5020b9bd ("workqueue: gut flush[_delayed]_work_sync()")
Signed-off-by: Alice Ryhl <aliceryhl@google.com>
---
Documentation/core-api/workqueue.rst | 7 ++++++-
kernel/workqueue.c | 17 ++++++++++++-----
2 files changed, 18 insertions(+), 6 deletions(-)
diff --git a/Documentation/core-api/workqueue.rst b/Documentation/core-api/workqueue.rst
index bb770f556568..007dee698ede 100644
--- a/Documentation/core-api/workqueue.rst
+++ b/Documentation/core-api/workqueue.rst
@@ -769,6 +769,8 @@ The work item's function should be trivially visible in the stack
trace.
+.. _workqueue_non_reentrance:
+
Non-reentrance Conditions
=========================
@@ -784,7 +786,10 @@ 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.
+required when breaking the conditions inside a work function; in particular,
+flush_work(), cancel_work_sync(), and disable_work_sync() only track the last
+queued instance and may return while an earlier execution on another workqueue
+is still running.
Kernel Inline Documentations Reference
diff --git a/kernel/workqueue.c b/kernel/workqueue.c
index d7acedfb8b27..5c7018ea0b48 100644
--- a/kernel/workqueue.c
+++ b/kernel/workqueue.c
@@ -4634,7 +4634,9 @@ static bool __flush_work(struct work_struct *work, bool from_cancel)
* @work: the work to flush
*
* Wait until @work has finished execution. @work is guaranteed to be idle
- * on return if it hasn't been requeued since flush started.
+ * on return if it hasn't been requeued since flush started and the
+ * :ref:`non-reentrance conditions <workqueue_non_reentrance>` in
+ * Documentation/core-api/workqueue.rst hold.
*
* Return:
* %true if flush_work() waited for the work to finish execution,
@@ -4764,9 +4766,14 @@ EXPORT_SYMBOL(cancel_work);
* @work: the work to cancel
*
* Cancel @work and wait for its execution to finish. This function can be used
- * even if the work re-queues itself or migrates to another workqueue. On return
- * from this function, @work is guaranteed to be not pending or executing on any
- * CPU as long as there aren't racing enqueues.
+ * even if the work re-queues itself. On return from this function, @work is
+ * guaranteed to be not pending or executing on any CPU as long as there aren't
+ * racing enqueues.
+ *
+ * Care must be taken if :ref:`the non-reentrance conditions <workqueue_non_reentrance>`
+ * in Documentation/core-api/workqueue.rst are not upheld for this work item.
+ * In that case, this function only waits for execution on the last queued
+ * workqueue.
*
* cancel_work_sync(&delayed_work->work) must not be used for delayed_work's.
* Use cancel_delayed_work_sync() instead.
@@ -4843,7 +4850,7 @@ EXPORT_SYMBOL_GPL(disable_work);
* @work: work item to disable
*
* Similar to disable_work() but also wait for @work to finish if currently
- * executing.
+ * executing; see cancel_work_sync().
*
* Must be called from a sleepable context if @work was last queued on a non-BH
* workqueue. Can also be called from non-hardirq atomic contexts including BH
--
2.56.1.703.gf848ed807c-goog
prev parent reply other threads:[~2026-11-18 17:10 UTC|newest]
Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-11-18 17:09 [PATCH 0/2] workqueue: fix cancel_work_sync() on ordered workqueues and clarify docs Alice Ryhl
2026-11-18 17:09 ` [PATCH 1/2] workqueue: fix cancel_work_sync() on ordered workqueues Alice Ryhl
2026-11-18 17:09 ` Alice Ryhl [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20261118-ordered-wq-cancel-v1-2-916e01f9affe@google.com \
--to=aliceryhl@google.com \
--cc=boqun@kernel.org \
--cc=boris.brezillon@collabora.com \
--cc=ckoenig.leichtzumerken@gmail.com \
--cc=corbet@lwn.net \
--cc=dakr@kernel.org \
--cc=dri-devel@lists.freedesktop.org \
--cc=intel-xe@lists.freedesktop.org \
--cc=jiangshanlai@gmail.com \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=liviu.dudau@arm.com \
--cc=matthew.brost@intel.com \
--cc=ojeda@kernel.org \
--cc=phasta@kernel.org \
--cc=rodrigo.vivi@intel.com \
--cc=rust-for-linux@vger.kernel.org \
--cc=steven.price@arm.com \
--cc=thomas.hellstrom@linux.intel.com \
--cc=tj@kernel.org \
--cc=work@onurozkan.dev \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
all inboxes | Powered by JetHome®