[RFC PATCH 1/2] workqueue: Add queue_*() functions, future schedule_*() replacement

[Marco Crivellari <marco.crivellari@suse.com>]

This is part of the workqueue refactoring. More details can be found at
the Link below.

The acqual schedule_*() interface used to schedule work items on a
workqueue doesn't distinguish between bound and unbound workqueue but
only system_percpu_wq is used. So introduce the bound and unbound versions.

To better reflect what these function does, rename them with a cleaner and
unified interface dropping the "schedule_*()" prefix and using "queue_*()".

This change introduce:
- queue_{bound|unbound}_work() with the bound version being the future
  replacement of schedule_work()

- queue_bound_work_on() as future replacement of schedule_work_on()

- queue_bound_delayed_work() as future replacement of
  schedule_delayed_work()

- add queue_unbound_delayed_work() to offer the unbound version

- queue_bound_delayed_work_on() as future replacement of
  schedule_delayed_work_on()

A further step would be the conversion of all the users to the new
introduced interfaces and the migration, whether locality is not
strictly required, to the unbound version.

In a future relase cycle and once users are migrated, the schedule_*()
interface will be removed.

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>
---
 include/linux/workqueue.h | 101 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 101 insertions(+)

diff --git a/include/linux/workqueue.h b/include/linux/workqueue.h
index ab6cb70ca1a5..f46379d937c9 100644
--- a/include/linux/workqueue.h
+++ b/include/linux/workqueue.h
@@ -732,12 +732,26 @@ static inline bool mod_delayed_work(struct workqueue_struct *wq,
  * @work: job to be done
  *
  * This puts a job on a specific cpu
+ *
+ * Note: this function will be replaced by queue_bound_work_on()
  */
 static inline bool schedule_work_on(int cpu, struct work_struct *work)
 {
 	return queue_work_on(cpu, system_percpu_wq, work);
 }
 
+/**
+ * queue_bound_work_on - put work task on a specific cpu
+ * @cpu: cpu to put the work task on
+ * @work: job to be done
+ *
+ * This puts a job on a specific cpu
+ */
+static inline bool queue_bound_work_on(int cpu, struct work_struct *work)
+{
+	return queue_work_on(cpu, system_percpu_wq, work);
+}
+
 /**
  * schedule_work - put work task in per-CPU workqueue
  * @work: job to be done
@@ -751,12 +765,53 @@ static inline bool schedule_work_on(int cpu, struct work_struct *work)
  *
  * Shares the same memory-ordering properties of queue_work(), cf. the
  * DocBook header of queue_work().
+ *
+ * Note: this function will be removed in future, use schedule_{bound|unbound}_work()
+ * instead.
  */
 static inline bool schedule_work(struct work_struct *work)
 {
 	return queue_work(system_percpu_wq, work);
 }
 
+/**
+ * queue_bound_work - put work task in per-CPU workqueue
+ * @work: job to be done
+ *
+ * Returns %false if @work was already on the system per-CPU workqueue and
+ * %true otherwise.
+ *
+ * This puts a job in the system per-CPU workqueue if it was not already
+ * queued and leaves it in the same position on the system per-CPU
+ * workqueue otherwise.
+ *
+ * Shares the same memory-ordering properties of queue_work(), cf. the
+ * DocBook header of queue_work().
+ */
+static inline bool queue_bound_work(struct work_struct *work)
+{
+	return queue_work(system_percpu_wq, work);
+}
+
+/**
+ * queue_unbound_work - put work task in unbound workqueue
+ * @work: job to be done
+ *
+ * Returns %false if @work was already on the system unbound workqueue and
+ * %true otherwise.
+ *
+ * This puts a job in the system unbound workqueue if it was not already
+ * queued and leaves it in the same position on the system unbound
+ * workqueue otherwise.
+ *
+ * Shares the same memory-ordering properties of queue_work(), cf. the
+ * DocBook header of queue_work().
+ */
+static inline bool queue_unbound_work(struct work_struct *work)
+{
+	return queue_work(system_dfl_wq, work);
+}
+
 /**
  * enable_and_queue_work - Enable and queue a work item on a specific workqueue
  * @wq: The target workqueue
@@ -832,6 +887,9 @@ extern void __warn_flushing_systemwide_wq(void)
  *
  * After waiting for a given time this puts a job in the system per-CPU
  * workqueue on the specified CPU.
+ *
+ * Note: this function will be removed. Please use queue_delayed_bound_work_on()
+ * instead
  */
 static inline bool schedule_delayed_work_on(int cpu, struct delayed_work *dwork,
 					    unsigned long delay)
@@ -839,6 +897,21 @@ static inline bool schedule_delayed_work_on(int cpu, struct delayed_work *dwork,
 	return queue_delayed_work_on(cpu, system_percpu_wq, dwork, delay);
 }
 
+/**
+ * queue_delayed_bound_work_on - queue work in per-CPU workqueue on CPU after delay
+ * @cpu: cpu to use
+ * @dwork: job to be done
+ * @delay: number of jiffies to wait
+ *
+ * After waiting for a given time this puts a job in the system per-CPU
+ * workqueue on the specified CPU.
+ */
+static inline bool queue_delayed_bound_work_on(int cpu, struct delayed_work *dwork,
+					    unsigned long delay)
+{
+	return queue_delayed_work_on(cpu, system_percpu_wq, dwork, delay);
+}
+
 /**
  * schedule_delayed_work - put work task in per-CPU workqueue after delay
  * @dwork: job to be done
@@ -853,6 +926,34 @@ static inline bool schedule_delayed_work(struct delayed_work *dwork,
 	return queue_delayed_work(system_percpu_wq, dwork, delay);
 }
 
+/**
+ * queue_delayed_bound_work - put work task in per-CPU workqueue after delay
+ * @dwork: job to be done
+ * @delay: number of jiffies to wait or 0 for immediate execution
+ *
+ * After waiting for a given time this puts a job in the system per-CPU
+ * workqueue.
+ */
+static inline bool queue_delayed_bound_work(struct delayed_work *dwork,
+					 unsigned long delay)
+{
+	return queue_delayed_work(system_percpu_wq, dwork, delay);
+}
+
+/**
+ * queue_delayed_unbound_work - put work task in unbound workqueue after delay
+ * @dwork: job to be done
+ * @delay: number of jiffies to wait or 0 for immediate execution
+ *
+ * After waiting for a given time this puts a job in the system unbound
+ * workqueue.
+ */
+static inline bool queue_delayed_unbound_work(struct delayed_work *dwork,
+					 unsigned long delay)
+{
+	return queue_delayed_work(system_dfl_wq, dwork, delay);
+}
+
 #ifndef CONFIG_SMP
 static inline long work_on_cpu(int cpu, long (*fn)(void *), void *arg)
 {
-- 
2.53.0