Re: [PATCH] Add kerneldoc for flush_scheduled_work()

Ingo Molnar
2009-08-12T09:41:35Z

* 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