lkml.org 
[lkml]   [2009]   [Aug]   [12]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    Date
    From
    SubjectRe: [PATCH] Add kerneldoc for flush_scheduled_work()

    * 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


    \
     
     \ /
      Last update: 2009-08-12 11:45    [W:0.052 / U:117.436 seconds]
    ©2003-2016 Jasper Spaans. hosted at Digital OceanAdvertise on this site