linux-kernel - Re: [PATCH] Add kerneldoc for flush_scheduled

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20090812094119.GC14734@elte.hu>
Date:	Wed, 12 Aug 2009 11:41:19 +0200
From:	Ingo Molnar <mingo@...e.hu>
To:	Alan Stern <stern@...land.harvard.edu>
Cc:	Andrew Morton <akpm@...ux-foundation.org>,
	James Bottomley <James.Bottomley@...senPartnership.com>,
	Kernel development list <linux-kernel@...r.kernel.org>
Subject: Re: [PATCH] Add kerneldoc for flush_scheduled_work()

* Alan Stern <stern@...land.harvard.edu> wrote:

> This patch (as1279) adds kerneldoc for flush_scheduled_work()
> containing a stern warning that the function should be avoided.
> 
> Signed-off-by: Alan Stern <stern@...land.harvard.edu>
> 
> ---
> 
> Index: usb-2.6/kernel/workqueue.c
> ===================================================================
> --- usb-2.6.orig/kernel/workqueue.c
> +++ usb-2.6/kernel/workqueue.c
> @@ -739,6 +739,24 @@ int schedule_on_each_cpu(work_func_t fun
>  	return 0;
>  }
>  
> +/**
> + * flush_scheduled_work - ensure that all work scheduled on keventd_wq has run to completion.
> + *
> + * Blocks until all works on the keventd_wq global workqueue have completed.
> + * We sleep until all works present upon entry have been handled, but we
> + * are not livelocked by new incoming ones.
> + *
> + * Use of this function is discouraged, as it is highly prone to deadlock.
> + * It should never be called from within a work routine on the global
> + * queue, and it should never be called while holding a mutex required
> + * by one of the works on the global queue.  But the fact that keventd_wq
> + * _is_ global means that it can contain works requiring practically any
> + * mutex.  Hence this routine shouldn't be called while holding any mutex.
> + *
> + * Consider using cancel_work_sync() or cancel_delayed_work_sync() instead.
> + * They don't do the same thing (they cancel the work instead of waiting
> + * for it to complete), but in most cases they will suffice.
> + */

Looks good - a small nit: please use proper/consistent line length, 
something like:

/**
 * flush_scheduled_work - ensure that all work scheduled on 
 *			  keventd_wq has run to completion
 *
 * Blocks until all works on the keventd_wq global workqueue have 
 * completed.  We sleep until all works present upon entry have been 
 * handled, but we are not livelocked by new incoming ones.
 *
 * Use of this function is discouraged, as it is highly prone to 
 * deadlock.  It should never be called from within a work routine 
 * on the global queue, and it should never be called while holding 
 * a mutex required by one of the works on the global queue.  But 
 * the fact that keventd_wq _is_ global means that it can contain 
 * works requiring practically any mutex.  Hence this routine 
 * shouldn't be called while holding any mutex.
 *
 * Consider using cancel_work_sync() or cancel_delayed_work_sync() 
 * instead.  They don't do the same thing (they cancel the work 
 * instead of waiting for it to complete), but in most cases they 
 * will suffice.
 */

Thanks,

	Ingo
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/