Merge branch 'for-3.12' of git://git.kernel.org/pub/scm/linux/kernel/git/tj/wq
Pull workqueue updates from Tejun Heo: "Nothing interesting. All are doc / comment updates" * 'for-3.12' of git://git.kernel.org/pub/scm/linux/kernel/git/tj/wq: workqueue: Correct/Drop references to gcwq in Documentation workqueue: Fix manage_workers() RETURNS description workqueue: Comment correction in file header workqueue: mark WQ_NON_REENTRANT deprecated
This commit is contained in:
commit
9ee52a1633
@ -85,32 +85,31 @@ workqueue.
|
|||||||
Special purpose threads, called worker threads, execute the functions
|
Special purpose threads, called worker threads, execute the functions
|
||||||
off of the queue, one after the other. If no work is queued, the
|
off of the queue, one after the other. If no work is queued, the
|
||||||
worker threads become idle. These worker threads are managed in so
|
worker threads become idle. These worker threads are managed in so
|
||||||
called thread-pools.
|
called worker-pools.
|
||||||
|
|
||||||
The cmwq design differentiates between the user-facing workqueues that
|
The cmwq design differentiates between the user-facing workqueues that
|
||||||
subsystems and drivers queue work items on and the backend mechanism
|
subsystems and drivers queue work items on and the backend mechanism
|
||||||
which manages thread-pools and processes the queued work items.
|
which manages worker-pools and processes the queued work items.
|
||||||
|
|
||||||
The backend is called gcwq. There is one gcwq for each possible CPU
|
There are two worker-pools, one for normal work items and the other
|
||||||
and one gcwq to serve work items queued on unbound workqueues. Each
|
for high priority ones, for each possible CPU and some extra
|
||||||
gcwq has two thread-pools - one for normal work items and the other
|
worker-pools to serve work items queued on unbound workqueues - the
|
||||||
for high priority ones.
|
number of these backing pools is dynamic.
|
||||||
|
|
||||||
Subsystems and drivers can create and queue work items through special
|
Subsystems and drivers can create and queue work items through special
|
||||||
workqueue API functions as they see fit. They can influence some
|
workqueue API functions as they see fit. They can influence some
|
||||||
aspects of the way the work items are executed by setting flags on the
|
aspects of the way the work items are executed by setting flags on the
|
||||||
workqueue they are putting the work item on. These flags include
|
workqueue they are putting the work item on. These flags include
|
||||||
things like CPU locality, reentrancy, concurrency limits, priority and
|
things like CPU locality, concurrency limits, priority and more. To
|
||||||
more. To get a detailed overview refer to the API description of
|
get a detailed overview refer to the API description of
|
||||||
alloc_workqueue() below.
|
alloc_workqueue() below.
|
||||||
|
|
||||||
When a work item is queued to a workqueue, the target gcwq and
|
When a work item is queued to a workqueue, the target worker-pool is
|
||||||
thread-pool is determined according to the queue parameters and
|
determined according to the queue parameters and workqueue attributes
|
||||||
workqueue attributes and appended on the shared worklist of the
|
and appended on the shared worklist of the worker-pool. For example,
|
||||||
thread-pool. For example, unless specifically overridden, a work item
|
unless specifically overridden, a work item of a bound workqueue will
|
||||||
of a bound workqueue will be queued on the worklist of either normal
|
be queued on the worklist of either normal or highpri worker-pool that
|
||||||
or highpri thread-pool of the gcwq that is associated to the CPU the
|
is associated to the CPU the issuer is running on.
|
||||||
issuer is running on.
|
|
||||||
|
|
||||||
For any worker pool implementation, managing the concurrency level
|
For any worker pool implementation, managing the concurrency level
|
||||||
(how many execution contexts are active) is an important issue. cmwq
|
(how many execution contexts are active) is an important issue. cmwq
|
||||||
@ -118,14 +117,14 @@ tries to keep the concurrency at a minimal but sufficient level.
|
|||||||
Minimal to save resources and sufficient in that the system is used at
|
Minimal to save resources and sufficient in that the system is used at
|
||||||
its full capacity.
|
its full capacity.
|
||||||
|
|
||||||
Each thread-pool bound to an actual CPU implements concurrency
|
Each worker-pool bound to an actual CPU implements concurrency
|
||||||
management by hooking into the scheduler. The thread-pool is notified
|
management by hooking into the scheduler. The worker-pool is notified
|
||||||
whenever an active worker wakes up or sleeps and keeps track of the
|
whenever an active worker wakes up or sleeps and keeps track of the
|
||||||
number of the currently runnable workers. Generally, work items are
|
number of the currently runnable workers. Generally, work items are
|
||||||
not expected to hog a CPU and consume many cycles. That means
|
not expected to hog a CPU and consume many cycles. That means
|
||||||
maintaining just enough concurrency to prevent work processing from
|
maintaining just enough concurrency to prevent work processing from
|
||||||
stalling should be optimal. As long as there are one or more runnable
|
stalling should be optimal. As long as there are one or more runnable
|
||||||
workers on the CPU, the thread-pool doesn't start execution of a new
|
workers on the CPU, the worker-pool doesn't start execution of a new
|
||||||
work, but, when the last running worker goes to sleep, it immediately
|
work, but, when the last running worker goes to sleep, it immediately
|
||||||
schedules a new worker so that the CPU doesn't sit idle while there
|
schedules a new worker so that the CPU doesn't sit idle while there
|
||||||
are pending work items. This allows using a minimal number of workers
|
are pending work items. This allows using a minimal number of workers
|
||||||
@ -135,19 +134,20 @@ Keeping idle workers around doesn't cost other than the memory space
|
|||||||
for kthreads, so cmwq holds onto idle ones for a while before killing
|
for kthreads, so cmwq holds onto idle ones for a while before killing
|
||||||
them.
|
them.
|
||||||
|
|
||||||
For an unbound wq, the above concurrency management doesn't apply and
|
For unbound workqueues, the number of backing pools is dynamic.
|
||||||
the thread-pools for the pseudo unbound CPU try to start executing all
|
Unbound workqueue can be assigned custom attributes using
|
||||||
work items as soon as possible. The responsibility of regulating
|
apply_workqueue_attrs() and workqueue will automatically create
|
||||||
concurrency level is on the users. There is also a flag to mark a
|
backing worker pools matching the attributes. The responsibility of
|
||||||
bound wq to ignore the concurrency management. Please refer to the
|
regulating concurrency level is on the users. There is also a flag to
|
||||||
API section for details.
|
mark a bound wq to ignore the concurrency management. Please refer to
|
||||||
|
the API section for details.
|
||||||
|
|
||||||
Forward progress guarantee relies on that workers can be created when
|
Forward progress guarantee relies on that workers can be created when
|
||||||
more execution contexts are necessary, which in turn is guaranteed
|
more execution contexts are necessary, which in turn is guaranteed
|
||||||
through the use of rescue workers. All work items which might be used
|
through the use of rescue workers. All work items which might be used
|
||||||
on code paths that handle memory reclaim are required to be queued on
|
on code paths that handle memory reclaim are required to be queued on
|
||||||
wq's that have a rescue-worker reserved for execution under memory
|
wq's that have a rescue-worker reserved for execution under memory
|
||||||
pressure. Else it is possible that the thread-pool deadlocks waiting
|
pressure. Else it is possible that the worker-pool deadlocks waiting
|
||||||
for execution contexts to free up.
|
for execution contexts to free up.
|
||||||
|
|
||||||
|
|
||||||
@ -166,25 +166,15 @@ resources, scheduled and executed.
|
|||||||
|
|
||||||
@flags:
|
@flags:
|
||||||
|
|
||||||
WQ_NON_REENTRANT
|
|
||||||
|
|
||||||
By default, a wq guarantees non-reentrance only on the same
|
|
||||||
CPU. A work item may not be executed concurrently on the same
|
|
||||||
CPU by multiple workers but is allowed to be executed
|
|
||||||
concurrently on multiple CPUs. This flag makes sure
|
|
||||||
non-reentrance is enforced across all CPUs. Work items queued
|
|
||||||
to a non-reentrant wq are guaranteed to be executed by at most
|
|
||||||
one worker system-wide at any given time.
|
|
||||||
|
|
||||||
WQ_UNBOUND
|
WQ_UNBOUND
|
||||||
|
|
||||||
Work items queued to an unbound wq are served by a special
|
Work items queued to an unbound wq are served by the special
|
||||||
gcwq which hosts workers which are not bound to any specific
|
woker-pools which host workers which are not bound to any
|
||||||
CPU. This makes the wq behave as a simple execution context
|
specific CPU. This makes the wq behave as a simple execution
|
||||||
provider without concurrency management. The unbound gcwq
|
context provider without concurrency management. The unbound
|
||||||
tries to start execution of work items as soon as possible.
|
worker-pools try to start execution of work items as soon as
|
||||||
Unbound wq sacrifices locality but is useful for the following
|
possible. Unbound wq sacrifices locality but is useful for
|
||||||
cases.
|
the following cases.
|
||||||
|
|
||||||
* Wide fluctuation in the concurrency level requirement is
|
* Wide fluctuation in the concurrency level requirement is
|
||||||
expected and using bound wq may end up creating large number
|
expected and using bound wq may end up creating large number
|
||||||
@ -209,10 +199,10 @@ resources, scheduled and executed.
|
|||||||
WQ_HIGHPRI
|
WQ_HIGHPRI
|
||||||
|
|
||||||
Work items of a highpri wq are queued to the highpri
|
Work items of a highpri wq are queued to the highpri
|
||||||
thread-pool of the target gcwq. Highpri thread-pools are
|
worker-pool of the target cpu. Highpri worker-pools are
|
||||||
served by worker threads with elevated nice level.
|
served by worker threads with elevated nice level.
|
||||||
|
|
||||||
Note that normal and highpri thread-pools don't interact with
|
Note that normal and highpri worker-pools don't interact with
|
||||||
each other. Each maintain its separate pool of workers and
|
each other. Each maintain its separate pool of workers and
|
||||||
implements concurrency management among its workers.
|
implements concurrency management among its workers.
|
||||||
|
|
||||||
@ -221,7 +211,7 @@ resources, scheduled and executed.
|
|||||||
Work items of a CPU intensive wq do not contribute to the
|
Work items of a CPU intensive wq do not contribute to the
|
||||||
concurrency level. In other words, runnable CPU intensive
|
concurrency level. In other words, runnable CPU intensive
|
||||||
work items will not prevent other work items in the same
|
work items will not prevent other work items in the same
|
||||||
thread-pool from starting execution. This is useful for bound
|
worker-pool from starting execution. This is useful for bound
|
||||||
work items which are expected to hog CPU cycles so that their
|
work items which are expected to hog CPU cycles so that their
|
||||||
execution is regulated by the system scheduler.
|
execution is regulated by the system scheduler.
|
||||||
|
|
||||||
@ -233,6 +223,10 @@ resources, scheduled and executed.
|
|||||||
|
|
||||||
This flag is meaningless for unbound wq.
|
This flag is meaningless for unbound wq.
|
||||||
|
|
||||||
|
Note that the flag WQ_NON_REENTRANT no longer exists as all workqueues
|
||||||
|
are now non-reentrant - any work item is guaranteed to be executed by
|
||||||
|
at most one worker system-wide at any given time.
|
||||||
|
|
||||||
@max_active:
|
@max_active:
|
||||||
|
|
||||||
@max_active determines the maximum number of execution contexts per
|
@max_active determines the maximum number of execution contexts per
|
||||||
@ -254,9 +248,9 @@ recommended.
|
|||||||
|
|
||||||
Some users depend on the strict execution ordering of ST wq. The
|
Some users depend on the strict execution ordering of ST wq. The
|
||||||
combination of @max_active of 1 and WQ_UNBOUND is used to achieve this
|
combination of @max_active of 1 and WQ_UNBOUND is used to achieve this
|
||||||
behavior. Work items on such wq are always queued to the unbound gcwq
|
behavior. Work items on such wq are always queued to the unbound
|
||||||
and only one work item can be active at any given time thus achieving
|
worker-pools and only one work item can be active at any given time thus
|
||||||
the same ordering property as ST wq.
|
achieving the same ordering property as ST wq.
|
||||||
|
|
||||||
|
|
||||||
5. Example Execution Scenarios
|
5. Example Execution Scenarios
|
||||||
|
@ -295,7 +295,12 @@ static inline unsigned int work_static(struct work_struct *work) { return 0; }
|
|||||||
* Documentation/workqueue.txt.
|
* Documentation/workqueue.txt.
|
||||||
*/
|
*/
|
||||||
enum {
|
enum {
|
||||||
WQ_NON_REENTRANT = 1 << 0, /* guarantee non-reentrance */
|
/*
|
||||||
|
* All wqs are now non-reentrant making the following flag
|
||||||
|
* meaningless. Will be removed.
|
||||||
|
*/
|
||||||
|
WQ_NON_REENTRANT = 1 << 0, /* DEPRECATED */
|
||||||
|
|
||||||
WQ_UNBOUND = 1 << 1, /* not bound to any cpu */
|
WQ_UNBOUND = 1 << 1, /* not bound to any cpu */
|
||||||
WQ_FREEZABLE = 1 << 2, /* freeze during suspend */
|
WQ_FREEZABLE = 1 << 2, /* freeze during suspend */
|
||||||
WQ_MEM_RECLAIM = 1 << 3, /* may be used for memory reclaim */
|
WQ_MEM_RECLAIM = 1 << 3, /* may be used for memory reclaim */
|
||||||
|
@ -16,9 +16,10 @@
|
|||||||
*
|
*
|
||||||
* This is the generic async execution mechanism. Work items as are
|
* This is the generic async execution mechanism. Work items as are
|
||||||
* executed in process context. The worker pool is shared and
|
* executed in process context. The worker pool is shared and
|
||||||
* automatically managed. There is one worker pool for each CPU and
|
* automatically managed. There are two worker pools for each CPU (one for
|
||||||
* one extra for works which are better served by workers which are
|
* normal work items and the other for high priority ones) and some extra
|
||||||
* not bound to any specific CPU.
|
* pools for workqueues which are not bound to any specific CPU - the
|
||||||
|
* number of these backing pools is dynamic.
|
||||||
*
|
*
|
||||||
* Please read Documentation/workqueue.txt for details.
|
* Please read Documentation/workqueue.txt for details.
|
||||||
*/
|
*/
|
||||||
@ -2033,8 +2034,11 @@ static bool maybe_destroy_workers(struct worker_pool *pool)
|
|||||||
* multiple times. Does GFP_KERNEL allocations.
|
* multiple times. Does GFP_KERNEL allocations.
|
||||||
*
|
*
|
||||||
* RETURNS:
|
* RETURNS:
|
||||||
* spin_lock_irq(pool->lock) which may be released and regrabbed
|
* %false if the pool don't need management and the caller can safely start
|
||||||
* multiple times. Does GFP_KERNEL allocations.
|
* processing works, %true indicates that the function released pool->lock
|
||||||
|
* and reacquired it to perform some management function and that the
|
||||||
|
* conditions that the caller verified while holding the lock before
|
||||||
|
* calling the function might no longer be true.
|
||||||
*/
|
*/
|
||||||
static bool manage_workers(struct worker *worker)
|
static bool manage_workers(struct worker *worker)
|
||||||
{
|
{
|
||||||
|
Loading…
Reference in New Issue
Block a user