[PATCH v2 0/2] workqueue: Make WQ_UNBOUND the default behavior

[PATCH v2 0/2] workqueue: Make WQ_UNBOUND the default behavior

[Marco Crivellari]

Hi,

Currently alloc_workqueue() make sure one among WQ_UNBOUND or WQ_PERCPU is
present. This is enforced warning and setting WQ_PERCPU as default when
alloc_workqueue() without WQ_PERCPU or WQ_UNBOUND.

[ P1 ] change this behavior: if no flags are specified, WQ_UNBOUND is
set by default, changing the default behavior when flags are not present.

The WARN_ONCE() when neither flags are present has been removed and it has
been replaced by pr_warn_once(): from now on, every alloc_users()
without WQ_PERCPU will be considered unbound.

Q: I decided to pr_warn_once() just to make sure users are aware of the new
behavior. It makes sense or we can just drop it directly?
I don't think the WARN_ONCE() is appropriate now, for this specific path.

[ P2 ] updates the documentation accordingly.

Thanks!

---
Changes in v1:
- if/else to add/drop WQ_UNBOUND/WQ_PERCPU moved before wq_size assignment

Link to v1: https://lore.kernel.org/all/20260903152204.401638-1-marco.crivellari@suse.com/

Marco Crivellari (2):
  workqueue: Make alloc_workqueue() unbound by default
  doc: Update WQ_UNBOUND documentation

 Documentation/core-api/workqueue.rst |  2 ++
 kernel/workqueue.c                   | 43 +++++++++++++++++-----------
 2 files changed, 29 insertions(+), 16 deletions(-)

-- 
2.55.0

[PATCH v2 1/2] workqueue: Make alloc_workqueue() unbound by default

[Marco Crivellari]

Currently alloc_workqueue() ensure that one among WQ_PERCPU or WQ_UNBOUND
is present. Now every user has one among these two flags.

In order to achive the future goal of removing WQ_UNBOUND from the code,
start changing the default behavior making alloc_workqueue() act this way:

  - if WQ_PERCPU and WQ_UNBOUND are present: remove WQ_PERCPU (as before)
  - if neither are present: add WQ_UNBOUND

The WARN_ONCE() when neither flags are present has been removed and it has
been replaced by pr_warn_once(): from now on, every alloc_users()
without WQ_PERCPU will be considered unbound.

The pr_warn_once() will be removed along with WQ_UNBOUND in the future.

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>
---
 kernel/workqueue.c | 43 +++++++++++++++++++++++++++----------------
 1 file changed, 27 insertions(+), 16 deletions(-)

diff --git a/kernel/workqueue.c b/kernel/workqueue.c
index 1ae3732a2c51..c1e5f2c6c8dd 100644
--- a/kernel/workqueue.c
+++ b/kernel/workqueue.c
@@ -5895,6 +5895,8 @@ static struct workqueue_struct *__alloc_workqueue(const char *fmt,
 	struct workqueue_struct *wq;
 	size_t wq_size;
 	int name_len;
+	bool wq_unbound_by_default = false;
+	bool wq_dropped_percpu = false;
 
 	if (flags & WQ_BH) {
 		if (WARN_ON_ONCE(flags & ~__WQ_BH_ALLOWS))
@@ -5903,6 +5905,24 @@ static struct workqueue_struct *__alloc_workqueue(const char *fmt,
 			return NULL;
 	}
 
+	/*
+	 * Every caller that doesn't explicitly specify WQ_PERCPU will be
+	 * unbound (WQ_UNBOUND) by default.
+	 *
+	 * If both flags are present at the same time, WQ_PERCPU will be
+	 * removed.
+	 *
+	 * This must happen before wq_size is computed below, since that
+	 * depends on the finalized WQ_UNBOUND flag.
+	 */
+	if (unlikely(!(flags & (WQ_UNBOUND | WQ_PERCPU)))) {
+		flags |= WQ_UNBOUND;
+		wq_unbound_by_default = true;
+	} else if (unlikely((flags & WQ_PERCPU) && (flags & WQ_UNBOUND))) {
+		flags &= ~WQ_PERCPU;
+		wq_dropped_percpu = true;
+	}
+
 	/* see the comment above the definition of WQ_POWER_EFFICIENT */
 	if ((flags & WQ_POWER_EFFICIENT) && wq_power_efficient)
 		flags = (flags & ~WQ_PERCPU) | WQ_UNBOUND;
@@ -5927,22 +5947,13 @@ static struct workqueue_struct *__alloc_workqueue(const char *fmt,
 		pr_warn_once("workqueue: name exceeds WQ_NAME_LEN. Truncating to: %s\n",
 			     wq->name);
 
-	/*
-	 * One among WQ_PERCPU and WQ_UNBOUND must be set, but not both.
-	 * - If neither is set, default to WQ_PERCPU
-	 * - If both are set, default to WQ_UNBOUND
-	 *
-	 * This code can be removed after workqueue are unbound by default
-	 */
-	if (unlikely(!(flags & (WQ_UNBOUND | WQ_PERCPU)))) {
-		WARN_ONCE(1, "workqueue: %s is using neither WQ_PERCPU or WQ_UNBOUND. "
-			  "Setting WQ_PERCPU.\n", wq->name);
-		flags |= WQ_PERCPU;
-	} else if (unlikely((flags & WQ_PERCPU) && (flags & WQ_UNBOUND))) {
-		WARN_ONCE(1, "workqueue: %s uses both WQ_PERCPU and WQ_UNBOUND. "
-			  "Dropped WQ_PERCPU, keeping WQ_UNBOUND.\n", wq->name);
-		flags &= ~WQ_PERCPU;
-	}
+	if (unlikely(wq_unbound_by_default))
+		pr_warn_once("workqueue: %s is using neither WQ_PERCPU or WQ_UNBOUND. "
+			     "Setting WQ_UNBOUND.\n", wq->name);
+
+	WARN_ONCE(wq_dropped_percpu,
+		  "workqueue: %s uses both WQ_PERCPU and WQ_UNBOUND. "
+		  "Dropped WQ_PERCPU, keeping WQ_UNBOUND.\n", wq->name);
 
 	if (flags & WQ_BH) {
 		/*
-- 
2.55.0

[PATCH v2 2/2] doc: Update WQ_UNBOUND documentation

[Marco Crivellari]

When WQ_PERCPU is not present the default behavior is now WQ_UNBOUND,
so update the documentation, reflecting this change.

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>
---
 Documentation/core-api/workqueue.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/core-api/workqueue.rst b/Documentation/core-api/workqueue.rst
index bb770f556568..3ca636e065ef 100644
--- a/Documentation/core-api/workqueue.rst
+++ b/Documentation/core-api/workqueue.rst
@@ -206,6 +206,8 @@ resources, scheduled and executed.
   * Long running CPU intensive workloads which can be better
     managed by the system scheduler.
 
+  Workqueue without ``WQ_PERCPU`` are unbound by default.
+
 ``WQ_FREEZABLE``
   A freezable wq participates in the freeze phase of the system
   suspend operations.  Work items on the wq are drained and no
-- 
2.55.0

Re: [PATCH v2 1/2] workqueue: Make alloc_workqueue() unbound by default

[Tejun Heo]

Hello, Marco.

On Thu, Sep 03, 2026 at 06:52:50PM +0200, Marco Crivellari wrote:
> +	if (unlikely(!(flags & (WQ_UNBOUND | WQ_PERCPU)))) {
> +		flags |= WQ_UNBOUND;
> +		wq_unbound_by_default = true;

WQ_BH without WQ_PERCPU passes the __WQ_BH_ALLOWS check above and then gets
WQ_UNBOUND here, putting a BH workqueue on an unbound pool. WQ_BH should
imply WQ_PERCPU.

Thanks.

-- 
tejun

Re: [PATCH v2 1/2] workqueue: Make alloc_workqueue() unbound by default

[Marco Crivellari]

On Thu, Sep 3, 2026 at 8:42 PM Tejun Heo <tj@kernel.org> wrote:
>
> Hello, Marco.
>
> On Thu, Sep 03, 2026 at 06:52:50PM +0200, Marco Crivellari wrote:
> > +     if (unlikely(!(flags & (WQ_UNBOUND | WQ_PERCPU)))) {
> > +             flags |= WQ_UNBOUND;
> > +             wq_unbound_by_default = true;
>
> WQ_BH without WQ_PERCPU passes the __WQ_BH_ALLOWS check above and then gets
> WQ_UNBOUND here, putting a BH workqueue on an unbound pool. WQ_BH should
> imply WQ_PERCPU.
>
> Thanks.

Hello Tejun,

Thanks for the review, I will fix it for v3.

-- 

Marco Crivellari

SUSE Labs