History

Merge branch 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/jikos/trivial

Pull trivial tree from Jiri Kosina: "The usual trivial updates all over the tree -- mostly typo fixes and documentation updates" * 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/jikos/trivial: (52 commits) doc: Documentation/cputopology.txt fix typo treewide: Convert retrun typos to return Fix comment typo for init_cma_reserved_pageblock Documentation/trace: Correcting and extending tracepoint documentation mm/hotplug: fix a typo in Documentation/memory-hotplug.txt power: Documentation: Update s2ram link doc: fix a typo in Documentation/00-INDEX Documentation/printk-formats.txt: No casts needed for u64/s64 doc: Fix typo "is is" in Documentations treewide: Fix printks with 0x%# zram: doc fixes Documentation/kmemcheck: update kmemcheck documentation doc: documentation/hwspinlock.txt fix typo PM / Hibernate: add section for resume options doc: filesystems : Fix typo in Documentations/filesystems scsi/megaraid fixed several typos in comments ppc: init_32: Fix error typo "CONFIG_START_KERNEL" treewide: Add __GFP_NOWARN to k.alloc calls with v.alloc fallbacks page_isolation: Fix a comment typo in test_pages_isolated() doc: fix a typo about irq affinity ...

Linus Torvalds committed 13 years ago

Commit 2e515bf2 parents 22e04f6 f8ea61e106 files · +269 −204Browse files

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

Unified · Split

kernel/workqueue.c+66−41
@@ -541,6 +541,8 @@ static int worker_pool_assign_id(struct worker_pool *pool) · 540 unmodified lines
541541 * This must be called either with pwq_lock held or sched RCU read locked.
542542 * If the pwq needs to be used beyond the locking in effect, the caller is
543543 * responsible for guaranteeing that the pwq stays online.
544+ *
545+ * Return: The unbound pool_workqueue for @node.
544546 */
545547 static struct pool_workqueue *unbound_pwq_by_node(struct workqueue_struct *wq,
546548 int node)
@@ -639,8 +641,6 @@ static struct pool_workqueue *get_work_pwq(struct work_struct *work) · 92 unmodified lines
639641 * get_work_pool - return the worker_pool a given work was associated with
640642 * @work: the work item of interest
641643 *
642− * Return the worker_pool @work was last associated with. %NULL if none.
643− *
644644 * Pools are created and destroyed under wq_pool_mutex, and allows read
645645 * access under sched-RCU read lock. As such, this function should be
646646 * called under wq_pool_mutex or with preemption disabled.
@@ -649,6 +649,8 @@ static struct pool_workqueue *get_work_pwq(struct work_struct *work) · 2 unmodified lines
649649 * mentioned locking is in effect. If the returned pool needs to be used
650650 * beyond the critical section, the caller is responsible for ensuring the
651651 * returned pool is and stays online.
652+ *
653+ * Return: The worker_pool @work was last associated with. %NULL if none.
652654 */
653655 static struct worker_pool *get_work_pool(struct work_struct *work)
654656 {
@@ -672,7 +674,7 @@ static struct worker_pool *get_work_pool(struct work_struct *work) · 17 unmodified lines
672674 * get_work_pool_id - return the worker pool ID a given work is associated with
673675 * @work: the work item of interest
674676 *
675− * Return the worker_pool ID @work was last associated with.
677+ * Return: The worker_pool ID @work was last associated with.
676678 * %WORK_OFFQ_POOL_NONE if none.
677679 */
678680 static int get_work_pool_id(struct work_struct *work)
@@ -831,7 +833,7 @@ void wq_worker_waking_up(struct task_struct *task, int cpu) · 152 unmodified lines
831833 * CONTEXT:
832834 * spin_lock_irq(rq->lock)
833835 *
834− * RETURNS:
836+ * Return:
835837 * Worker task on @cpu to wake up, %NULL if none.
836838 */
837839 struct task_struct *wq_worker_sleeping(struct task_struct *task, int cpu)
@@ -966,8 +968,8 @@ static inline void worker_clr_flags(struct worker *worker, unsigned int flags) · 128 unmodified lines
966968 * CONTEXT:
967969 * spin_lock_irq(pool->lock).
968970 *
969− * RETURNS:
970− * Pointer to worker which is executing @work if found, NULL
971+ * Return:
972+ * Pointer to worker which is executing @work if found, %NULL
971973 * otherwise.
972974 */
973975 static struct worker *find_worker_executing_work(struct worker_pool *pool,
@@ -1155,14 +1157,16 @@ out_put: · 181 unmodified lines
11551157 * @flags: place to store irq state
11561158 *
11571159 * Try to grab PENDING bit of @work. This function can handle @work in any
1158− * stable state - idle, on timer or on worklist. Return values are
1160+ * stable state - idle, on timer or on worklist.
11591161 *
1162+ * Return:
11601163 * 1 if @work was pending and we successfully stole PENDING
11611164 * 0 if @work was idle and we claimed PENDING
11621165 * -EAGAIN if PENDING couldn't be grabbed at the moment, safe to busy-retry
11631166 * -ENOENT if someone else is canceling @work, this state may persist
11641167 * for arbitrarily long
11651168 *
1169+ * Note:
11661170 * On >= 0 return, the caller owns @work's PENDING bit. To avoid getting
11671171 * interrupted while holding PENDING and @work off queue, irq must be
11681172 * disabled on entry. This, combined with delayed_work->timer being
@@ -1404,10 +1408,10 @@ retry: · 235 unmodified lines
14041408 * @wq: workqueue to use
14051409 * @work: work to queue
14061410 *
1407− * Returns %false if @work was already on a queue, %true otherwise.
1408− *
14091411 * We queue the work to a specific CPU, the caller must ensure it
14101412 * can't go away.
1413+ *
1414+ * Return: %false if @work was already on a queue, %true otherwise.
14111415 */
14121416 bool queue_work_on(int cpu, struct workqueue_struct *wq,
14131417 struct work_struct *work)
@@ -1477,7 +1481,7 @@ static void __queue_delayed_work(int cpu, struct workqueue_struct *wq, · 63 unmodified lines
14771481 * @dwork: work to queue
14781482 * @delay: number of jiffies to wait before queueing
14791483 *
1480− * Returns %false if @work was already on a queue, %true otherwise. If
1484+ * Return: %false if @work was already on a queue, %true otherwise. If
14811485 * @delay is zero and @dwork is idle, it will be scheduled for immediate
14821486 * execution.
14831487 */
@@ -1513,7 +1517,7 @@ EXPORT_SYMBOL(queue_delayed_work_on); · 29 unmodified lines
15131517 * zero, @work is guaranteed to be scheduled immediately regardless of its
15141518 * current state.
15151519 *
1516− * Returns %false if @dwork was idle and queued, %true if @dwork was
1520+ * Return: %false if @dwork was idle and queued, %true if @dwork was
15171521 * pending and its timer was modified.
15181522 *
15191523 * This function is safe to call from any context including IRQ handler.
@@ -1628,7 +1632,7 @@ static void worker_leave_idle(struct worker *worker) · 108 unmodified lines
16281632 * Might sleep. Called without any lock but returns with pool->lock
16291633 * held.
16301634 *
1631− * RETURNS:
1635+ * Return:
16321636 * %true if the associated pool is online (@worker is successfully
16331637 * bound), %false if offline.
16341638 */
@@ -1689,7 +1693,7 @@ static struct worker *alloc_worker(void) · 54 unmodified lines
16891693 * CONTEXT:
16901694 * Might sleep. Does GFP_KERNEL allocations.
16911695 *
1692− * RETURNS:
1696+ * Return:
16931697 * Pointer to the newly created worker.
16941698 */
16951699 static struct worker *create_worker(struct worker_pool *pool)
@@ -1789,6 +1793,8 @@ static void start_worker(struct worker *worker) · 93 unmodified lines
17891793 * @pool: the target pool
17901794 *
17911795 * Grab the managership of @pool and create and start a new worker for it.
1796+ *
1797+ * Return: 0 on success. A negative error code otherwise.
17921798 */
17931799 static int create_and_start_worker(struct worker_pool *pool)
17941800 {
@@ -1933,7 +1939,7 @@ static void pool_mayday_timeout(unsigned long __pool) · 138 unmodified lines
19331939 * multiple times. Does GFP_KERNEL allocations. Called only from
19341940 * manager.
19351941 *
1936− * RETURNS:
1942+ * Return:
19371943 * %false if no action was taken and pool->lock stayed locked, %true
19381944 * otherwise.
19391945 */
@@ -1990,7 +1996,7 @@ restart: · 50 unmodified lines
19901996 * spin_lock_irq(pool->lock) which may be released and regrabbed
19911997 * multiple times. Called only from manager.
19921998 *
1993− * RETURNS:
1999+ * Return:
19942000 * %false if no action was taken and pool->lock stayed locked, %true
19952001 * otherwise.
19962002 */
@@ -2033,7 +2039,7 @@ static bool maybe_destroy_workers(struct worker_pool *pool) · 36 unmodified lines
20332039 * spin_lock_irq(pool->lock) which may be released and regrabbed
20342040 * multiple times. Does GFP_KERNEL allocations.
20352041 *
2036− * RETURNS:
2042+ * Return:
20372043 * %false if the pool don't need management and the caller can safely start
20382044 * processing works, %true indicates that the function released pool->lock
20392045 * and reacquired it to perform some management function and that the
@@ -2259,6 +2265,8 @@ static void process_scheduled_works(struct worker *worker) · 219 unmodified lines
22592265 * work items regardless of their specific target workqueue. The only
22602266 * exception is work items which belong to workqueues with a rescuer which
22612267 * will be explained in rescuer_thread().
2268+ *
2269+ * Return: 0
22622270 */
22632271 static int worker_thread(void *__worker)
22642272 {
@@ -2357,6 +2365,8 @@ sleep: · 92 unmodified lines
23572365 * those works so that forward progress can be guaranteed.
23582366 *
23592367 * This should happen rarely.
2368+ *
2369+ * Return: 0
23602370 */
23612371 static int rescuer_thread(void *__rescuer)
23622372 {
@@ -2529,7 +2539,7 @@ static void insert_wq_barrier(struct pool_workqueue *pwq, · 166 unmodified lines
25292539 * CONTEXT:
25302540 * mutex_lock(wq->mutex).
25312541 *
2532− * RETURNS:
2542+ * Return:
25332543 * %true if @flush_color >= 0 and there's something to flush. %false
25342544 * otherwise.
25352545 */
@@ -2850,7 +2860,7 @@ static bool __flush_work(struct work_struct *work) · 314 unmodified lines
28502860 * Wait until @work has finished execution. @work is guaranteed to be idle
28512861 * on return if it hasn't been requeued since flush started.
28522862 *
2853− * RETURNS:
2863+ * Return:
28542864 * %true if flush_work() waited for the work to finish execution,
28552865 * %false if it was already idle.
28562866 */
@@ -2902,7 +2912,7 @@ static bool __cancel_work_timer(struct work_struct *work, bool is_dwork) · 45 unmodified lines
29022912 * The caller must ensure that the workqueue on which @work was last
29032913 * queued can't be destroyed before this function returns.
29042914 *
2905− * RETURNS:
2915+ * Return:
29062916 * %true if @work was pending, %false otherwise.
29072917 */
29082918 bool cancel_work_sync(struct work_struct *work)
@@ -2919,7 +2929,7 @@ EXPORT_SYMBOL_GPL(cancel_work_sync); · 10 unmodified lines
29192929 * immediate execution. Like flush_work(), this function only
29202930 * considers the last queueing instance of @dwork.
29212931 *
2922− * RETURNS:
2932+ * Return:
29232933 * %true if flush_work() waited for the work to finish execution,
29242934 * %false if it was already idle.
29252935 */
@@ -2937,11 +2947,15 @@ EXPORT_SYMBOL(flush_delayed_work); · 11 unmodified lines
29372947 * cancel_delayed_work - cancel a delayed work
29382948 * @dwork: delayed_work to cancel
29392949 *
2940− * Kill off a pending delayed_work. Returns %true if @dwork was pending
2941− * and canceled; %false if wasn't pending. Note that the work callback
2942− * function may still be running on return, unless it returns %true and the
2943− * work doesn't re-arm itself. Explicitly flush or use
2944− * cancel_delayed_work_sync() to wait on it.
2950+ * Kill off a pending delayed_work.
2951+ *
2952+ * Return: %true if @dwork was pending and canceled; %false if it wasn't
2953+ * pending.
2954+ *
2955+ * Note:
2956+ * The work callback function may still be running on return, unless
2957+ * it returns %true and the work doesn't re-arm itself. Explicitly flush or
2958+ * use cancel_delayed_work_sync() to wait on it.
29452959 *
29462960 * This function is safe to call from any context including IRQ handler.
29472961 */
@@ -2970,7 +2984,7 @@ EXPORT_SYMBOL(cancel_delayed_work); · 22 unmodified lines
29702984 *
29712985 * This is cancel_work_sync() for delayed works.
29722986 *
2973− * RETURNS:
2987+ * Return:
29742988 * %true if @dwork was pending, %false otherwise.
29752989 */
29762990 bool cancel_delayed_work_sync(struct delayed_work *dwork)
@@ -2987,7 +3001,7 @@ EXPORT_SYMBOL(cancel_delayed_work_sync); · 10 unmodified lines
29873001 * system workqueue and blocks until all CPUs have completed.
29883002 * schedule_on_each_cpu() is very slow.
29893003 *
2990− * RETURNS:
3004+ * Return:
29913005 * 0 on success, -errno on failure.
29923006 */
29933007 int schedule_on_each_cpu(work_func_t func)
@@ -3055,7 +3069,7 @@ EXPORT_SYMBOL(flush_scheduled_work); · 61 unmodified lines
30553069 * Executes the function immediately if process context is available,
30563070 * otherwise schedules the function for delayed execution.
30573071 *
3058− * Returns: 0 - function was executed
3072+ * Return: 0 - function was executed
30593073 * 1 - function was scheduled for execution
30603074 */
30613075 int execute_in_process_context(work_func_t fn, struct execute_work *ew)
@@ -3315,7 +3329,7 @@ static void wq_device_release(struct device *dev) · 253 unmodified lines
33153329 * apply_workqueue_attrs() may race against userland updating the
33163330 * attributes.
33173331 *
3318− * Returns 0 on success, -errno on failure.
3332+ * Return: 0 on success, -errno on failure.
33193333 */
33203334 int workqueue_sysfs_register(struct workqueue_struct *wq)
33213335 {
@@ -3408,7 +3422,9 @@ void free_workqueue_attrs(struct workqueue_attrs *attrs) · 86 unmodified lines
34083422 * @gfp_mask: allocation mask to use
34093423 *
34103424 * Allocate a new workqueue_attrs, initialize with default settings and
3411− * return it. Returns NULL on failure.
3425+ * return it.
3426+ *
3427+ * Return: The allocated new workqueue_attr on success. %NULL on failure.
34123428 */
34133429 struct workqueue_attrs *alloc_workqueue_attrs(gfp_t gfp_mask)
34143430 {
@@ -3467,7 +3483,8 @@ static bool wqattrs_equal(const struct workqueue_attrs *a, · 52 unmodified lines
34673483 * @pool: worker_pool to initialize
34683484 *
34693485 * Initiailize a newly zalloc'd @pool. It also allocates @pool->attrs.
3470− * Returns 0 on success, -errno on failure. Even on failure, all fields
3486+ *
3487+ * Return: 0 on success, -errno on failure. Even on failure, all fields
34713488 * inside @pool proper are initialized and put_unbound_pool() can be called
34723489 * on @pool safely to release it.
34733490 */
@@ -3574,9 +3591,12 @@ static void put_unbound_pool(struct worker_pool *pool) · 100 unmodified lines
35743591 * Obtain a worker_pool which has the same attributes as @attrs, bump the
35753592 * reference count and return it. If there already is a matching
35763593 * worker_pool, it will be used; otherwise, this function attempts to
3577− * create a new one. On failure, returns NULL.
3594+ * create a new one.
35783595 *
35793596 * Should be called with wq_pool_mutex held.
3597+ *
3598+ * Return: On success, a worker_pool with the same attributes as @attrs.
3599+ * On failure, %NULL.
35803600 */
35813601 static struct worker_pool *get_unbound_pool(const struct workqueue_attrs *attrs)
35823602 {
@@ -3812,9 +3832,7 @@ static void free_unbound_pwq(struct pool_workqueue *pwq) · 229 unmodified lines
38123832 *
38133833 * Calculate the cpumask a workqueue with @attrs should use on @node. If
38143834 * @cpu_going_down is >= 0, that cpu is considered offline during
3815− * calculation. The result is stored in @cpumask. This function returns
3816− * %true if the resulting @cpumask is different from @attrs->cpumask,
3817− * %false if equal.
3835+ * calculation. The result is stored in @cpumask.
38183836 *
38193837 * If NUMA affinity is not enabled, @attrs->cpumask is always used. If
38203838 * enabled and @node has online CPUs requested by @attrs, the returned
@@ -3823,6 +3841,9 @@ static void free_unbound_pwq(struct pool_workqueue *pwq) · 2 unmodified lines
38233841 *
38243842 * The caller is responsible for ensuring that the cpumask of @node stays
38253843 * stable.
3844+ *
3845+ * Return: %true if the resulting @cpumask is different from @attrs->cpumask,
3846+ * %false if equal.
38263847 */
38273848 static bool wq_calc_node_cpumask(const struct workqueue_attrs *attrs, int node,
38283849 int cpu_going_down, cpumask_t *cpumask)
@@ -3876,8 +3897,9 @@ static struct pool_workqueue *numa_pwq_tbl_install(struct workqueue_struct *wq, · 47 unmodified lines
38763897 * items finish. Note that a work item which repeatedly requeues itself
38773898 * back-to-back will stay on its current pwq.
38783899 *
3879− * Performs GFP_KERNEL allocations. Returns 0 on success and -errno on
3880− * failure.
3900+ * Performs GFP_KERNEL allocations.
3901+ *
3902+ * Return: 0 on success and -errno on failure.
38813903 */
38823904 int apply_workqueue_attrs(struct workqueue_struct *wq,
38833905 const struct workqueue_attrs *attrs)
@@ -4345,6 +4367,8 @@ EXPORT_SYMBOL_GPL(workqueue_set_max_active); · 461 unmodified lines
43454367 *
43464368 * Determine whether %current is a workqueue rescuer. Can be used from
43474369 * work functions to determine whether it's being run off the rescuer task.
4370+ *
4371+ * Return: %true if %current is a workqueue rescuer. %false otherwise.
43484372 */
43494373 bool current_is_workqueue_rescuer(void)
43504374 {
@@ -4368,7 +4392,7 @@ bool current_is_workqueue_rescuer(void) · 17 unmodified lines
43684392 * workqueue being congested on one CPU doesn't mean the workqueue is also
43694393 * contested on other CPUs / NUMA nodes.
43704394 *
4371− * RETURNS:
4395+ * Return:
43724396 * %true if congested, %false otherwise.
43734397 */
43744398 bool workqueue_congested(int cpu, struct workqueue_struct *wq)
@@ -4401,7 +4425,7 @@ EXPORT_SYMBOL_GPL(workqueue_congested); · 26 unmodified lines
44014425 * synchronization around this function and the test result is
44024426 * unreliable and only useful as advisory hints or for debugging.
44034427 *
4404− * RETURNS:
4428+ * Return:
44054429 * OR'd bitmask of WORK_BUSY_* bits.
44064430 */
44074431 unsigned int work_busy(struct work_struct *work)
@@ -4779,9 +4803,10 @@ static void work_for_cpu_fn(struct work_struct *work) · 371 unmodified lines
47794803 * @fn: the function to run
47804804 * @arg: the function arg
47814805 *
4782− * This will return the value @fn returns.
47834806 * It is up to the caller to ensure that the cpu doesn't go offline.
47844807 * The caller must not hold any locks which would prevent @fn from completing.
4808+ *
4809+ * Return: The value @fn returns.
47854810 */
47864811 long work_on_cpu(int cpu, long (*fn)(void *), void *arg)
47874812 {
@@ -4853,7 +4878,7 @@ void freeze_workqueues_begin(void) · 65 unmodified lines
48534878 * CONTEXT:
48544879 * Grabs and releases wq_pool_mutex.
48554880 *
4856− * RETURNS:
4881+ * Return:
48574882 * %true if some freezable workqueues are still busy. %false if freezing
48584883 * is complete.
48594884 */