include/linux/workqueue.h

1 /* SPDX-License-Identifier: GPL-2.0 */
3  * workqueue.h --- work queue handling for Linux.
23 #define work_data_bits(work) ((unsigned long *)(&(work)->data))
62 	/* data contains off-queue information when !WORK_STRUCT_PWQ */
74 	WORK_OFFQ_LEFT		= BITS_PER_LONG - WORK_OFFQ_POOL_SHIFT,
85 /* Convenience constants - of type 'unsigned long', not 'enum'! */
87 #define WORK_OFFQ_POOL_NONE	((1ul << WORK_OFFQ_POOL_BITS) - 1)
90 #define WORK_STRUCT_FLAG_MASK    ((1ul << WORK_STRUCT_FLAG_BITS) - 1)
101 	/* target workqueue and CPU ->timer uses to queue ->work */
110 	/* target workqueue ->rcu uses to queue ->work */
126  * struct workqueue_attrs - A struct for workqueue attributes.
146 	 * @__pod_cpumask: internal attribute used to create per-pod pools
150 	 * Per-pod unbound worker pools are used to improve locality. Always a
151 	 * subset of ->cpumask. A workqueue can be associated with multiple
160 	 * If clear, workqueue will make a best-effort attempt at starting the
177 	 * CPU pods are used to improve execution locality of unbound work
266 		(_work)->data = (atomic_long_t) WORK_DATA_INIT();	\
267 		lockdep_init_map(&(_work)->lockdep_map, "(work_completion)"#_work, (_key), 0); \
268 		INIT_LIST_HEAD(&(_work)->entry);			\
269 		(_work)->func = (_func);				\
275 		(_work)->data = (atomic_long_t) WORK_DATA_INIT();	\
276 		INIT_LIST_HEAD(&(_work)->entry);			\
277 		(_work)->func = (_func);				\
299 		INIT_WORK(&(_work)->work, (_func));			\
300 		__init_timer(&(_work)->timer,				\
307 		INIT_WORK_ONSTACK(&(_work)->work, (_func));		\
308 		__init_timer_on_stack(&(_work)->timer,			\
326 	INIT_WORK(&(_work)->work, (_func))
329 	INIT_WORK_ONSTACK(&(_work)->work, (_func))
332  * work_pending - Find out whether a work item is currently pending
339  * delayed_work_pending - Find out whether a delayable work item is currently
344 	work_pending(&(w)->work)
348  * Documentation/core-api/workqueue.rst.
359 	 * Per-cpu workqueues are generally preferred because they tend to
360 	 * show better performance thanks to cache locality.  Per-cpu
367 	 * however, for example, a per-cpu work item scheduled from an
370 	 * turn may lead to more scheduling choices which are sub-optimal
373 	 * Workqueues marked with WQ_POWER_EFFICIENT are per-cpu by default
375 	 * specified.  Per-cpu workqueues which are identified to
376 	 * contribute significantly to power-consumption are identified and
397  * System-wide workqueues which are always present.
400  * Multi-CPU multi-threaded.  There are users which expect relatively
411  * any specific CPU, not concurrency managed, and all queued works are
420  * they are same as their non-power-efficient counterparts - e.g.
433  * alloc_workqueue - allocate a workqueue
436  * @max_active: max in-flight work items per CPU, 0 for default
441  * Documentation/core-api/workqueue.rst.
450  * alloc_ordered_workqueue - allocate an ordered workqueue
523  * queue_work - queue work on a workqueue
532  * Memory-ordering properties:  If it returns %true, guarantees that all stores
552  * queue_delayed_work - queue work on a workqueue after delay
567  * mod_delayed_work - modify delay of or queue a delayed work
582  * schedule_work_on - put work task on a specific cpu
586  * This puts a job on a specific cpu
594  * schedule_work - put work task in global workqueue
597  * Returns %false if @work was already on the kernel-global workqueue and
600  * This puts a job in the kernel-global workqueue if it was not already
601  * queued and leaves it in the same position on the kernel-global
604  * Shares the same memory-ordering properties of queue_work(), cf. the
613  * Detect attempt to flush system-wide workqueues at compile time when possible.
614  * Warn attempt to flush system-wide workqueues at runtime.
616  * See https://lkml.kernel.org/r/49925af7-78a8-a3dd-bce6-cfc02e1a9236@I-love.SAKURA.ne.jp
617  * for reasons and steps for converting system-wide workqueues into local workqueues.
620 	__compiletime_warning("Please avoid flushing system-wide workqueues.");
652  * schedule_delayed_work_on - queue work in global workqueue on CPU after delay
657  * After waiting for a given time this puts a job in the kernel-global
667  * schedule_delayed_work - put work task in global workqueue after delay
671  * After waiting for a given time this puts a job in the kernel-global