Re: [PATCH] Add kerneldoc for flush_scheduled_work()

[Ingo Molnar <mingo@elte.hu>]

* Alan Stern <stern@rowland.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@rowland.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