insert_wq_barrier(9)

okay bestie, welcome to insert_wq_barrier(9) from the Kernel API Manual ✨ this one is lowkey about making one work wait on another, and the ordering tea is very specific. let's get into it 🫶

✨ NAME ✨

insert_wq_barrier — insert a barrier work 💅

🌸 SYNOPSIS 🌸

void insert_wq_barrier (struct pool_workqueue *pwq , struct wq_barrier
       *barr , struct work_struct *target , struct worker *worker );

🎀 ARGUMENTS 🎀

• pwq — the pwq you're inserting the barrier into 💫
• barr — the wq_barrier that's getting inserted 🧚
• target — the target work you're attaching barr to 🌸
• worker — the worker currently executing target; it's NULL if target is not executing 🫶

🦋 DESCRIPTION 🦋

barr gets linked to target in a way that means barr is completed only after target finishes execution 💅. that's the whole point. quick vibe check: the ordering guarantee is observed only with respect to target and on the local cpu — literally just that scope, bestie 🫶.

Currently, a queued barrier can't be canceled 🚫. why? because try_to_grab_pending can't determine whether the work to be grabbed is at the head of the queue and thus can't clear the LINKED flag of the previous work while there must be a valid next work after a work with the LINKED flag set. that's the tea, and it means no cancellation for queued barriers right now 😭.

and one more lil note: when worker is non-NULL, target may be modified underneath us, so we can't reliably determine pwq from target 👀.

🔒 CONTEXT 🔒

you're doing this under raw_spin_lock_irq(pool->lock) 🔒.

👑 SEE ALSO 👑

the whole (9) friend group lives in the kernel file ./kernel/workqueue.c: for_each_pool(9), for_each_pool_worker(9), for_each_pwq(9), worker_pool_assign_id(9), unbound_effective_cpumask(9), get_work_pool(9), worker_set_flags(9), worker_clr_flags(9), worker_enter_idle(9), worker_leave_idle(9), find_worker_executing_work(9), move_linked_works(9), assign_work(9), kick_pool_pick(9), kick_pool(9), wq_worker_running(9), wq_worker_sleeping(9), wq_worker_tick(9), wq_worker_last_func(9), wq_node_nr_active(9), wq_update_node_max_active(9), get_pwq(9), put_pwq(9), put_pwq_unlocked(9), pwq_tryinc_nr_active(9), pwq_activate_first_inactive(9), unplug_oldest_pwq(9), node_activate_pending_pwq(9), pwq_dec_nr_active(9), pwq_dec_nr_in_flight(9), try_to_grab_pending(9), work_grab_pending(9), insert_work(9), queue_work_on(9), select_numa_node_cpu(9), queue_work_node(9), queue_delayed_work_on(9), mod_delayed_work_on(9), queue_rcu_work(9), worker_attach_to_pool(9), worker_detach_from_pool(9), create_worker(9), set_worker_dying(9), idle_worker_timeout(9), idle_cull_fn(9), maybe_create_worker(9), manage_workers(9), process_one_work(9), process_scheduled_works(9), worker_thread(9), rescuer_thread(9), check_flush_dependency(9), flush_workqueue_prep_pwqs(9), __flush_workqueue(9), drain_workqueue(9), flush_work(9), flush_delayed_work(9), flush_rcu_work(9), cancel_work_sync(9), cancel_delayed_work(9), cancel_delayed_work_sync(9), disable_work(9), disable_work_sync(9), enable_work(9), disable_delayed_work(9), disable_delayed_work_sync(9), enable_delayed_work(9), schedule_on_each_cpu(9), execute_in_process_context(9), free_workqueue_attrs(9), alloc_workqueue_attrs(9), init_worker_pool(9), put_unbound_pool(9), get_unbound_pool(9), wq_calc_pod_cpumask(9), apply_workqueue_attrs(9), unbound_wq_update_pwq(9), wq_adjust_max_active(9), destroy_workqueue(9), workqueue_set_max_active(9), workqueue_set_min_active(9), current_work(9), current_is_workqueue_rescuer(9), current_is_workqueue_mem_reclaim(9), workqueue_congested(9), work_busy(9), set_worker_desc(9), print_worker_info(9), show_one_workqueue(9), show_one_worker_pool(9), show_all_workqueues(9), show_freezable_workqueues(9), rebind_workers(9), restore_unbound_workers_cpumask(9), work_on_cpu_key(9), freeze_workqueues_begin(9), freeze_workqueues_busy(9), thaw_workqueues(9), workqueue_unbound_housekeeping_update(9), workqueue_set_unbound_cpumask(9), workqueue_sysfs_register(9), workqueue_sysfs_unregister(9), workqueue_init_early(9), workqueue_init(9), llc_count_cores(9), llc_populate_cpu_shard_id(9), precompute_cache_shard_ids(9), workqueue_init_topology(9).

mwah 💋 this page came from the ./kernel source tree, October 2026 edition, and yes it's still insert_wq_barrier(9) at the bottom — iykyk 🫶