mirror of https://lore.kernel.org/lkml/
 help / color / mirror / Atom feed
From: Marco Crivellari <marco.crivellari@suse.com>
To: linux-kernel@vger.kernel.org
Cc: Tejun Heo <tj@kernel.org>, Lai Jiangshan <jiangshanlai@gmail.com>,
	Frederic Weisbecker <frederic@kernel.org>,
	Sebastian Andrzej Siewior <bigeasy@linutronix.de>,
	Marco Crivellari <marco.crivellari@suse.com>,
	Michal Hocko <mhocko@suse.com>, Breno Leitao <leitao@debian.org>
Subject: [PATCH v6 2/2] workqueue: doc: Update WQ_UNBOUND and WQ_BH documentation
Date: Mon, 16 Nov 2026 16:50:51 +0100	[thread overview]
Message-ID: <20261116155051.157875-3-marco.crivellari@suse.com> (raw)
In-Reply-To: <20261116155051.157875-1-marco.crivellari@suse.com>

When WQ_PERCPU is not present the default behavior is now WQ_UNBOUND,
so update the documentation accordingly, including the guideline that
recommended bound workqueues.

WQ_BH workqueues are the exception: they are always per-CPU, so
WQ_PERCPU is implied for them and WQ_UNBOUND is rejected. Mention that
in the WQ_BH section.

Link: https://lore.kernel.org/all/20250221112003.1dSuoGyc@linutronix.de/
Suggested-by: Tejun Heo <tj@kernel.org>
Signed-off-by: Marco Crivellari <marco.crivellari@suse.com>
Reviewed-by: Breno Leitao <leitao@debian.org>
---
 Documentation/core-api/workqueue.rst | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/Documentation/core-api/workqueue.rst b/Documentation/core-api/workqueue.rst
index 54697907f2b0..ef8f613ce402 100644
--- a/Documentation/core-api/workqueue.rst
+++ b/Documentation/core-api/workqueue.rst
@@ -178,7 +178,7 @@ resources, scheduled and executed.
   queueing CPU's softirq context in the queueing order.
 
   All BH workqueues must have 0 ``max_active`` and ``WQ_HIGHPRI`` is the
-  only allowed additional flag.
+  only allowed additional flag. ``WQ_PERCPU`` is implied.
 
   BH work items cannot sleep. All other features such as delayed queueing,
   flushing and canceling are supported.
@@ -190,6 +190,9 @@ resources, scheduled and executed.
   This flag is the complement of ``WQ_UNBOUND``.
 
 ``WQ_UNBOUND``
+  Workqueues without ``WQ_PERCPU`` are unbound by default, except for
+  ``WQ_BH`` workqueues, which are always per-CPU.
+
   Work items queued to an unbound wq are served by the special
   worker-pools which host workers which are not bound to any
   specific CPU.  This makes the wq behave as a simple execution
@@ -375,9 +378,9 @@ Guidelines
   wq and potentially lead to deadlock. It should utilize its own
   dedicated workqueue rather than the system wq.
 
-* Unless work items are expected to consume a huge amount of CPU
-  cycles, using a bound wq is usually beneficial due to the increased
-  level of locality in wq operations and work item execution.
+* Use ``WQ_PERCPU`` only if work items benefit from the increased level
+  of locality in wq operations and work item execution. Otherwise, the
+  default unbound wq is usually the better choice.
 
 
 Affinity Scopes
-- 
2.56.0


      parent reply	other threads:[~2026-11-16 15:51 UTC|newest]

Thread overview: 3+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2026-11-16 15:50 [PATCH v6 0/2] workqueue: Make WQ_UNBOUND the default behavior Marco Crivellari
2026-11-16 15:50 ` [PATCH v6 1/2] workqueue: Make alloc_workqueue() unbound by default Marco Crivellari
2026-11-16 15:50 ` Marco Crivellari [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=20261116155051.157875-3-marco.crivellari@suse.com \
    --to=marco.crivellari@suse.com \
    --cc=bigeasy@linutronix.de \
    --cc=frederic@kernel.org \
    --cc=jiangshanlai@gmail.com \
    --cc=leitao@debian.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=mhocko@suse.com \
    --cc=tj@kernel.org \
    /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®