[PATCH 1/3] rename cancel_rearming_delayed_work() to cancel_delayed_work_sync()

[PATCH 1/3] rename cancel_rearming_delayed_work() to cancel_delayed_work_sync()

[Oleg Nesterov]

Imho, the current naming of cancel_xxx workqueue functions is very confusing.

	cancel_delayed_work()
	cancel_rearming_delayed_work()
	cancel_rearming_delayed_workqueue()	// obsolete

	cancel_work_sync()

This looks as if the first 2 functions differ in "type" of their argument which
is not true any longer, nowadays the difference is the behaviour.

The semantics of cancel_rearming_delayed_work(dwork) was changed significantly,
it doesn't require that dwork rearms itself, and cancels dwork synchronously.

Rename it to cancel_delayed_work_sync(). This matches cancel_delayed_work() and
cancel_work_sync(). Re-create cancel_rearming_delayed_work() as a simple inline
obsolete wrapper, like cancel_rearming_delayed_workqueue().

Signed-off-by: Oleg Nesterov <oleg@tv-sign.ru>

--- OLD/include/linux/workqueue.h~1_rename	2007-05-17 23:05:13.000000000 +0400
+++ OLD/include/linux/workqueue.h	2007-06-02 14:26:54.000000000 +0400
@@ -166,14 +166,21 @@ static inline int cancel_delayed_work(st
 	return ret;
 }
 
-extern void cancel_rearming_delayed_work(struct delayed_work *work);
+extern void cancel_delayed_work_sync(struct delayed_work *work);
 
-/* Obsolete. use cancel_rearming_delayed_work() */
+/* Obsolete. use cancel_delayed_work_sync() */
 static inline
 void cancel_rearming_delayed_workqueue(struct workqueue_struct *wq,
 					struct delayed_work *work)
 {
-	cancel_rearming_delayed_work(work);
+	cancel_delayed_work_sync(work);
+}
+
+/* Obsolete. use cancel_delayed_work_sync() */
+static inline
+void cancel_rearming_delayed_work(struct delayed_work *work)
+{
+	cancel_delayed_work_sync(work);
 }
 
 #endif
--- OLD/kernel/workqueue.c~1_rename	2007-05-19 01:55:03.000000000 +0400
+++ OLD/kernel/workqueue.c	2007-07-01 15:02:12.000000000 +0400
@@ -486,13 +486,13 @@ void cancel_work_sync(struct work_struct
 EXPORT_SYMBOL_GPL(cancel_work_sync);
 
 /**
- * cancel_rearming_delayed_work - reliably kill off a delayed work.
+ * cancel_delayed_work_sync - reliably kill off a delayed work.
  * @dwork: the delayed work struct
  *
  * It is possible to use this function if @dwork rearms itself via queue_work()
  * or queue_delayed_work(). See also the comment for cancel_work_sync().
  */
-void cancel_rearming_delayed_work(struct delayed_work *dwork)
+void cancel_delayed_work_sync(struct delayed_work *dwork)
 {
 	while (!del_timer(&dwork->timer) &&
 	       !try_to_grab_pending(&dwork->work))
@@ -500,7 +500,7 @@ void cancel_rearming_delayed_work(struct
 	wait_on_work(&dwork->work);
 	work_clear_pending(&dwork->work);
 }
-EXPORT_SYMBOL(cancel_rearming_delayed_work);
+EXPORT_SYMBOL(cancel_delayed_work_sync);
 
 static struct workqueue_struct *keventd_wq __read_mostly;
 

Re: [PATCH 1/3] rename cancel_rearming_delayed_work() to cancel_delayed_work_sync()

[Jarek Poplawski]

On Sun, Jul 01, 2007 at 07:36:29PM +0400, Oleg Nesterov wrote:
> Imho, the current naming of cancel_xxx workqueue functions is very confusing.
> 
> 	cancel_delayed_work()
> 	cancel_rearming_delayed_work()
> 	cancel_rearming_delayed_workqueue()	// obsolete
> 
> 	cancel_work_sync()
> 
> This looks as if the first 2 functions differ in "type" of their argument which
> is not true any longer, nowadays the difference is the behaviour.
> 
> The semantics of cancel_rearming_delayed_work(dwork) was changed significantly,
> it doesn't require that dwork rearms itself, and cancels dwork synchronously.
> 
> Rename it to cancel_delayed_work_sync(). This matches cancel_delayed_work() and
> cancel_work_sync(). Re-create cancel_rearming_delayed_work() as a simple inline
> obsolete wrapper, like cancel_rearming_delayed_workqueue().

I like the idea of this change, but have some doubt: "_sync"
usually suggests the main difference from "" (or _nosync) is:
_sync waits for something, while _nosync doesn't wait and
instantly returns.

Here it's a bit complicated: cancel_delayed_work() (so nosync),
actually can wait a little too (on del_timer_sync). And
cancel_rearming_delayed_work() is really more universal now,
but still the main difference is this should be used with works
that rearm (at least sometimes). If there is no rearming - no
reason for this function (of course not forbidden too)  - and
maybe it better helps to remember the difference?

So, I would probably prefer cancel_delayed_work_rearming(), but
I don't write/read enough code with this, and I may be wrong.
I'm not agains the current proposal too - maybe one more reason
for sync?

Regards,
Jarek P.

Re: [PATCH 1/3] rename cancel_rearming_delayed_work() to cancel_delayed_work_sync()

[Oleg Nesterov]

On 07/02, Jarek Poplawski wrote:
>
> On Sun, Jul 01, 2007 at 07:36:29PM +0400, Oleg Nesterov wrote:
> > Imho, the current naming of cancel_xxx workqueue functions is very confusing.
> > 
> > 	cancel_delayed_work()
> > 	cancel_rearming_delayed_work()
> > 	cancel_rearming_delayed_workqueue()	// obsolete
> > 
> > 	cancel_work_sync()
> > 
> > This looks as if the first 2 functions differ in "type" of their argument which
> > is not true any longer, nowadays the difference is the behaviour.
> > 
> > The semantics of cancel_rearming_delayed_work(dwork) was changed significantly,
> > it doesn't require that dwork rearms itself, and cancels dwork synchronously.
> > 
> > Rename it to cancel_delayed_work_sync(). This matches cancel_delayed_work() and
> > cancel_work_sync(). Re-create cancel_rearming_delayed_work() as a simple inline
> > obsolete wrapper, like cancel_rearming_delayed_workqueue().
> 
> I like the idea of this change, but have some doubt: "_sync"
> usually suggests the main difference from "" (or _nosync) is:
> _sync waits for something, while _nosync doesn't wait and
> instantly returns.

Yes, but we already have cancel_work_sync().

> Here it's a bit complicated: cancel_delayed_work() (so nosync),
> actually can wait a little too (on del_timer_sync). And
> cancel_rearming_delayed_work() is really more universal now,
> but still the main difference is this should be used with works
> that rearm (at least sometimes). If there is no rearming - no
> reason for this function (of course not forbidden too)  - and
> maybe it better helps to remember the difference?

There is a reason even if no rearming. We have a lot of

	cancel_delayed_work();
	flush_workqueue();

This should be converted to use cancel_delayed_work_sync().

Note also that both cancel_work_sync() and cancel_rearming_delayed_work()
can be used on any work (rearming or not) and both imply "flush".
I think the "_rearming" part of the name is very confusing, and a "good"
name should be consistent with cancel_work_sync() and cancel_delayed_work()
which we already have.

Oleg.

Re: [PATCH 1/3] rename cancel_rearming_delayed_work() to cancel_delayed_work_sync()

[Jarek Poplawski]

On Mon, Jul 02, 2007 at 04:14:47PM +0400, Oleg Nesterov wrote:
> On 07/02, Jarek Poplawski wrote:
> >
> > On Sun, Jul 01, 2007 at 07:36:29PM +0400, Oleg Nesterov wrote:
> > > Imho, the current naming of cancel_xxx workqueue functions is very confusing.
> > > 
> > > 	cancel_delayed_work()
> > > 	cancel_rearming_delayed_work()
> > > 	cancel_rearming_delayed_workqueue()	// obsolete
> > > 
> > > 	cancel_work_sync()
> > > 
> > > This looks as if the first 2 functions differ in "type" of their argument which
> > > is not true any longer, nowadays the difference is the behaviour.
> > > 
> > > The semantics of cancel_rearming_delayed_work(dwork) was changed significantly,
> > > it doesn't require that dwork rearms itself, and cancels dwork synchronously.
> > > 
> > > Rename it to cancel_delayed_work_sync(). This matches cancel_delayed_work() and
> > > cancel_work_sync(). Re-create cancel_rearming_delayed_work() as a simple inline
> > > obsolete wrapper, like cancel_rearming_delayed_workqueue().
> > 
> > I like the idea of this change, but have some doubt: "_sync"
> > usually suggests the main difference from "" (or _nosync) is:
> > _sync waits for something, while _nosync doesn't wait and
> > instantly returns.
> 
> Yes, but we already have cancel_work_sync().

And it's OK because it actually can block. Some confusion
could appear (maybe to me only) if we would add cancel_work()
which would also ... block.

> 
> > Here it's a bit complicated: cancel_delayed_work() (so nosync),
> > actually can wait a little too (on del_timer_sync). And
> > cancel_rearming_delayed_work() is really more universal now,
> > but still the main difference is this should be used with works
> > that rearm (at least sometimes). If there is no rearming - no
> > reason for this function (of course not forbidden too)  - and
> > maybe it better helps to remember the difference?
> 
> There is a reason even if no rearming. We have a lot of
> 
> 	cancel_delayed_work();
> 	flush_workqueue();
> 
> This should be converted to use cancel_delayed_work_sync().
> 
> Note also that both cancel_work_sync() and cancel_rearming_delayed_work()
> can be used on any work (rearming or not) and both imply "flush".
> I think the "_rearming" part of the name is very confusing, and a "good"
> name should be consistent with cancel_work_sync() and cancel_delayed_work()
> which we already have.

I know, but I'm a little afraid of "overloading" the "_sync":
here it's kind of double sync (can block plus really finish
something). I wonder if this way is used elsewhere in linux.

But I see the more serious reason for it is: it's in your next
patches and we don't want to waste time. So, I'll try to check
this in the evening, and if nothing strange - I'll send acks
tomorrow (of course - not that I think they are needed...).

Thanks,
Jarek P.

Re: [PATCH 1/3] rename cancel_rearming_delayed_work() to cancel_delayed_work_sync()

[Jarek Poplawski]

On Sun, Jul 01, 2007 at 07:36:29PM +0400, Oleg Nesterov wrote:
> Imho, the current naming of cancel_xxx workqueue functions is very confusing.
> 
> 	cancel_delayed_work()
> 	cancel_rearming_delayed_work()
> 	cancel_rearming_delayed_workqueue()	// obsolete
> 
> 	cancel_work_sync()
> 
> This looks as if the first 2 functions differ in "type" of their argument which
> is not true any longer, nowadays the difference is the behaviour.
> 
> The semantics of cancel_rearming_delayed_work(dwork) was changed significantly,
> it doesn't require that dwork rearms itself, and cancels dwork synchronously.
> 
> Rename it to cancel_delayed_work_sync(). This matches cancel_delayed_work() and
> cancel_work_sync(). Re-create cancel_rearming_delayed_work() as a simple inline
> obsolete wrapper, like cancel_rearming_delayed_workqueue().
> 
> Signed-off-by: Oleg Nesterov <oleg@tv-sign.ru>

Acked-by: Jarek Poplawski <jarkao2@o2.pl>