leandrof/linux
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

workqueue: Correct/Drop references to gcwq in Documentation

Browse Source 
No functional changes. This patch fixes the post gcwq comments in
Documentation/workqueue.txt.

tj: Whitespace adjustments.  Minor updates.

Signed-off-by: Libin <huawei.libin@huawei.com>
Signed-off-by: Tejun Heo <tj@kernel.org>
This commit is contained in:
Libin 2013-08-21 08:50:41 +08:00 committed by Tejun Heo
parent 2d498db981
commit 546d30c4a2
1 changed files with 36 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
Documentation/workqueue.txt
View File

@ -85,16 +85,16 @@ 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
@ -104,13 +104,12 @@ things like CPU locality, concurrency limits, priority and 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.
@ -168,13 +168,13 @@ resources, scheduled and executed.
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
@ -199,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.
@ -211,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.
@ -248,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