History

workqueue: update comments and a warning message

* Update incorrect and add missing synchronization labels. * Update incorrect or misleading comments. Add new comments where clarification is necessary. Reformat / rephrase some comments. * drain_workqueue() can be used separately from destroy_workqueue() but its warning message was incorrectly referring to destruction. Other than the warning message change, this patch doesn't make any functional changes.

Tejun Heo committed 13 years ago

Commit c5aa87b1 parent 983ca251 file · +44 −40Browse files

Showing the changes to kernel/workqueue.c (1 of 1 file). Show all

Unified · Split

kernel/workqueue.c+44−40
@@ -145,7 +145,7 @@ struct worker_pool { · 144 unmodified lines
145145 struct timer_list idle_timer; /* L: worker idle timeout */
146146 struct timer_list mayday_timer; /* L: SOS timer for workers */
147147
148− /* workers are chained either in busy_hash or idle_list */
148+ /* a workers is either on busy_hash or idle_list, or the manager */
149149 DECLARE_HASHTABLE(busy_hash, BUSY_WORKER_HASH_ORDER);
150150 /* L: hash of busy workers */
151151
@@ -154,8 +154,8 @@ struct worker_pool { · 2 unmodified lines
154154 struct ida worker_ida; /* L: for worker IDs */
155155
156156 struct workqueue_attrs *attrs; /* I: worker attributes */
157− struct hlist_node hash_node; /* R: unbound_pool_hash node */
158− int refcnt; /* refcnt for unbound pools */
157+ struct hlist_node hash_node; /* W: unbound_pool_hash node */
158+ int refcnt; /* W: refcnt for unbound pools */
159159
160160 /*
161161 * The current concurrency level. As it's likely to be accessed
@@ -213,8 +213,8 @@ struct wq_flusher { · 51 unmodified lines
213213 struct wq_device;
214214
215215 /*
216− * The externally visible workqueue abstraction is an array of
217− * per-CPU workqueues:
216+ * The externally visible workqueue. It relays the issued work items to
217+ * the appropriate worker_pool through its pool_workqueues.
218218 */
219219 struct workqueue_struct {
220220 unsigned int flags; /* W: WQ_* flags */
@@ -247,9 +247,10 @@ struct workqueue_struct { · 26 unmodified lines
247247
248248 static struct kmem_cache *pwq_cache;
249249
250−/* hash of all unbound pools keyed by pool->attrs */
250+/* W: hash of all unbound pools keyed by pool->attrs */
251251 static DEFINE_HASHTABLE(unbound_pool_hash, UNBOUND_POOL_HASH_ORDER);
252252
253+/* I: attributes used when instantiating standard unbound pools on demand */
253254 static struct workqueue_attrs *unbound_std_wq_attrs[NR_STD_WORKER_POOLS];
254255
255256 struct workqueue_struct *system_wq __read_mostly;
@@ -434,16 +435,13 @@ static DEFINE_SPINLOCK(workqueue_lock); · 178 unmodified lines
434435 static LIST_HEAD(workqueues);
435436 static bool workqueue_freezing; /* W: have wqs started freezing? */
436437
437−/*
438− * The CPU and unbound standard worker pools. The unbound ones have
439− * POOL_DISASSOCIATED set, and their workers have WORKER_UNBOUND set.
440− */
438+/* the per-cpu worker pools */
441439 static DEFINE_PER_CPU_SHARED_ALIGNED(struct worker_pool [NR_STD_WORKER_POOLS],
442440 cpu_worker_pools);
443441
444442 /*
445− * idr of all pools. Modifications are protected by workqueue_lock. Read
446− * accesses are protected by sched-RCU protected.
443+ * R: idr of all pools. Modifications are protected by workqueue_lock.
444+ * Read accesses are protected by sched-RCU protected.
447445 */
448446 static DEFINE_IDR(worker_pool_idr);
449447
@@ -890,13 +888,12 @@ static inline void worker_clr_flags(struct worker *worker, unsigned int flags) · 440 unmodified lines
890888 * recycled work item as currently executing and make it wait until the
891889 * current execution finishes, introducing an unwanted dependency.
892890 *
893− * This function checks the work item address, work function and workqueue
894− * to avoid false positives. Note that this isn't complete as one may
895− * construct a work function which can introduce dependency onto itself
896− * through a recycled work item. Well, if somebody wants to shoot oneself
897− * in the foot that badly, there's only so much we can do, and if such
898− * deadlock actually occurs, it should be easy to locate the culprit work
899− * function.
891+ * This function checks the work item address and work function to avoid
892+ * false positives. Note that this isn't complete as one may construct a
893+ * work function which can introduce dependency onto itself through a
894+ * recycled work item. Well, if somebody wants to shoot oneself in the
895+ * foot that badly, there's only so much we can do, and if such deadlock
896+ * actually occurs, it should be easy to locate the culprit work function.
900897 *
901898 * CONTEXT:
902899 * spin_lock_irq(pool->lock).
@@ -1187,9 +1184,9 @@ static void insert_work(struct pool_workqueue *pwq, struct work_struct *work, · 284 unmodified lines
11871184 get_pwq(pwq);
11881185
11891186 /*
1190− * Ensure either worker_sched_deactivated() sees the above
1191− * list_add_tail() or we see zero nr_running to avoid workers
1192− * lying around lazily while there are works to be processed.
1187+ * Ensure either wq_worker_sleeping() sees the above
1188+ * list_add_tail() or we see zero nr_running to avoid workers lying
1189+ * around lazily while there are works to be processed.
11931190 */
11941191 smp_mb();
11951192
@@ -1790,6 +1787,10 @@ static struct worker *create_worker(struct worker_pool *pool) · 594 unmodified lines
17901787 if (IS_ERR(worker->task))
17911788 goto fail;
17921789
1790+ /*
1791+ * set_cpus_allowed_ptr() will fail if the cpumask doesn't have any
1792+ * online CPUs. It'll be re-applied when any of the CPUs come up.
1793+ */
17931794 set_user_nice(worker->task, pool->attrs->nice);
17941795 set_cpus_allowed_ptr(worker->task, pool->attrs->cpumask);
17951796
@@ -1950,8 +1951,8 @@ static void pool_mayday_timeout(unsigned long __pool) · 154 unmodified lines
19501951 * sent to all rescuers with works scheduled on @pool to resolve
19511952 * possible allocation deadlock.
19521953 *
1953− * On return, need_to_create_worker() is guaranteed to be false and
1954− * may_start_working() true.
1954+ * On return, need_to_create_worker() is guaranteed to be %false and
1955+ * may_start_working() %true.
19551956 *
19561957 * LOCKING:
19571958 * spin_lock_irq(pool->lock) which may be released and regrabbed
@@ -1959,7 +1960,7 @@ static void pool_mayday_timeout(unsigned long __pool) · 1 unmodified line
19591960 * manager.
19601961 *
19611962 * RETURNS:
1962− * false if no action was taken and pool->lock stayed locked, true
1963+ * %false if no action was taken and pool->lock stayed locked, %true
19631964 * otherwise.
19641965 */
19651966 static bool maybe_create_worker(struct worker_pool *pool)
@@ -2016,7 +2017,7 @@ restart: · 50 unmodified lines
20162017 * multiple times. Called only from manager.
20172018 *
20182019 * RETURNS:
2019− * false if no action was taken and pool->lock stayed locked, true
2020+ * %false if no action was taken and pool->lock stayed locked, %true
20202021 * otherwise.
20212022 */
20222023 static bool maybe_destroy_workers(struct worker_pool *pool)
@@ -2268,11 +2269,11 @@ static void process_scheduled_works(struct worker *worker) · 245 unmodified lines
22682269 * worker_thread - the worker thread function
22692270 * @__worker: self
22702271 *
2271− * The worker thread function. There are NR_CPU_WORKER_POOLS dynamic pools
2272− * of these per each cpu. These workers process all works regardless of
2273− * their specific target workqueue. The only exception is works which
2274− * belong to workqueues with a rescuer which will be explained in
2275− * rescuer_thread().
2272+ * The worker thread function. All workers belong to a worker_pool -
2273+ * either a per-cpu one or dynamic unbound one. These workers process all
2274+ * work items regardless of their specific target workqueue. The only
2275+ * exception is work items which belong to workqueues with a rescuer which
2276+ * will be explained in rescuer_thread().
22762277 */
22772278 static int worker_thread(void *__worker)
22782279 {
@@ -2600,11 +2601,8 @@ static bool flush_workqueue_prep_pwqs(struct workqueue_struct *wq, · 321 unmodified lines
26002601 * flush_workqueue - ensure that any scheduled work has run to completion.
26012602 * @wq: workqueue to flush
26022603 *
2603− * Forces execution of the workqueue and blocks until its completion.
2604− * This is typically used in driver shutdown handlers.
2605− *
2606− * We sleep until all works which were queued on entry have been handled,
2607− * but we are not livelocked by new incoming ones.
2604+ * This function sleeps until all work items which were queued on entry
2605+ * have finished execution, but it is not livelocked by new incoming ones.
26082606 */
26092607 void flush_workqueue(struct workqueue_struct *wq)
26102608 {
@@ -2794,7 +2792,7 @@ reflush: · 183 unmodified lines
27942792
27952793 if (++flush_cnt == 10 ||
27962794 (flush_cnt % 100 == 0 && flush_cnt <= 1000))
2797− pr_warn("workqueue %s: flush on destruction isn't complete after %u tries\n",
2795+ pr_warn("workqueue %s: drain_workqueue() isn't complete after %u tries\n",
27982796 wq->name, flush_cnt);
27992797
28002798 local_irq_enable();
@@ -3576,7 +3574,9 @@ static void rcu_free_pool(struct rcu_head *rcu) · 775 unmodified lines
35763574 * @pool: worker_pool to put
35773575 *
35783576 * Put @pool. If its refcnt reaches zero, it gets destroyed in sched-RCU
3579− * safe manner.
3577+ * safe manner. get_unbound_pool() calls this function on its failure path
3578+ * and this function should be able to release pools which went through,
3579+ * successfully or not, init_worker_pool().
35803580 */
35813581 static void put_unbound_pool(struct worker_pool *pool)
35823582 {
@@ -3602,7 +3602,11 @@ static void put_unbound_pool(struct worker_pool *pool) · 19 unmodified lines
36023602
36033603 spin_unlock_irq(&workqueue_lock);
36043604
3605− /* lock out manager and destroy all workers */
3605+ /*
3606+ * Become the manager and destroy all workers. Grabbing
3607+ * manager_arb prevents @pool's workers from blocking on
3608+ * manager_mutex.
3609+ */
36063610 mutex_lock(&pool->manager_arb);
36073611 spin_lock_irq(&pool->lock);
36083612
@@ -4339,7 +4343,7 @@ EXPORT_SYMBOL_GPL(work_on_cpu); · 730 unmodified lines
43394343 * freeze_workqueues_begin - begin freezing workqueues
43404344 *
43414345 * Start freezing workqueues. After this function returns, all freezable
4342− * workqueues will queue new works to their frozen_works list instead of
4346+ * workqueues will queue new works to their delayed_works list instead of
43434347 * pool->worklist.
43444348 *
43454349 * CONTEXT:

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t