alloc_workqueue(9)

✨ alloc_workqueue — allocate a workqueue ✨

okay so this is a page straight out of the Kernel API Manual, bestie, and it's literally about making a brand-new workqueue. iconic behavior. let's get into it 💅

---

🎀 SYNOPSIS 🎀

struct workqueue_struct * alloc_workqueue (const char *fmt , unsigned
int flags , int max_active , ... );

---

🌸 ARGUMENTS 🌸

• fmt — a printf format for the name of the workqueue. yes, the name is a format string, so it can be fancy 🎀
• flags — the WQ_* flags. all the vibes live here.
• max_active — the max in-flight work items. pass 0 and you get the default, no stress 🫶
• ... — the args for fmt. the format string's little entourage ✨

---

💖 DESCRIPTION 💖

okay so first thing: this depends on what kind of workqueue you're making, and max_active behaves differently for each. pay attention bestie, this is the main character part 👑

For a per-cpu workqueue, max_active limits the number of in-flight work items for each CPU. like, max_active of 1 means each CPU can be executing at most one work item for the workqueue. one. per CPU. that's it. ⭐

For unbound workqueues, max_active limits the number of in-flight work items for the whole system. so max_active of 16 means there can be at most 16 work items executing for the workqueue across the entire whole system. global girlies 🌈

---

now here's the spicy bit 🌶️ — sharing the same active counter for an unbound workqueue across multiple NUMA nodes can be expensive, so instead max_active gets distributed to each NUMA node according to the proportion of the number of online CPUs, and then enforced independently. math girl summer 💀

---

⚠️ and because of online CPU distribution, a node may end up with a per-node max_active that's significantly lower than max_active. that can lead to deadlocks if the per-node concurrency limit drops below the maximum number of interdependent work items for the workqueue. not cute. not slay. actual deadlock energy. 😭

---

to guarantee forward progress regardless of online CPU distribution, the concurrency limit on every node is guaranteed to be equal to or greater than min_active, which is set to min(max_active, WQ_DFL_MIN_ACTIVE). 🧚

and the consequence? the sum of the per-node max_active's may be larger than max_active. yeah. the numbers don't have to add up and that's on purpose, periodt 💅

---

for the detailed info on WQ_flags, please refer to Documentation/core-api/workqueue.rst. go read it, iykyk 📖

---

🦋 RETURN 🦋

pointer to the allocated workqueue on success, NULL on failure. simple. clean. either you ate or you didn't 🍓

---

👑 SEE ALSO 👑

kernel file ./include/linux/workqueue.h and the whole squad:

• struct workqueue_attrs(9)
• work_pending(9)
• delayed_work_pending(9)
• devm_alloc_workqueue(9)
• alloc_workqueue_lockdep_map(9)
• alloc_ordered_workqueue_lockdep_map(9)
• alloc_ordered_workqueue(9)
• queue_work(9)
• queue_delayed_work(9)
• mod_delayed_work(9)
• schedule_work_on(9)
• schedule_work(9)
• enable_and_queue_work(9)
• schedule_delayed_work_on(9)
• schedule_delayed_work(9)

---

okay that's the whole page bestie, you're officially a workqueue girlie now 💜 this one came from the Kernel API Manual, sourced out of ./include/linux, dated October 2026, and it's filed under alloc_workqueue(9). mwah 💋✨