[PATCH] workqueue: Better document teardown for delayed_work

[PATCH] workqueue: Better document teardown for delayed_work

[Philipp Stanner]

destroy_workqueue() does not ensure that non-pending work submitted with
queue_delayed_work() gets cancelled. The caller has to ensure that
manually.

Add this information about delayed_work in destroy_workqueue()'s
docstring.

Signed-off-by: Philipp Stanner <phasta@kernel.org>
---
Hi,

I have seen this WARN_ON [1] fire in my code for testing the DRM GPU
Scheduler, where a (non-delayed) work_item from workqueue A submits
delayed_work to workqueue B [2].

From my experience so far and reading the documentation, I didn't expect
this to happen.

Assuming this is wanted behavior (?), I propose documenting this more
explicitly. Or could it be possible to modify destroy_workqueue() so
that it takes care of submitted delayed_work()?

Greetings,
P.

[1] https://elixir.bootlin.com/linux/v6.14-rc6/source/kernel/workqueue.c#L2257
[2] https://gitlab.freedesktop.org/pstanner/schedleaker/-/blob/goodmemmodell/schedleaker.c?ref_type=heads#L291
---
 kernel/workqueue.c | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/kernel/workqueue.c b/kernel/workqueue.c
index bfe030b443e2..5a30efe7ddeb 100644
--- a/kernel/workqueue.c
+++ b/kernel/workqueue.c
@@ -5837,6 +5837,9 @@ static bool pwq_busy(struct pool_workqueue *pwq)
  * @wq: target workqueue
  *
  * Safely destroy a workqueue. All work currently pending will be done first.
+ * This does not apply to non-pending work that was submitted with
+ * queue_delayed_work(). Such work must be cancelled manually before calling
+ * this function.
  */
 void destroy_workqueue(struct workqueue_struct *wq)
 {
-- 
2.48.1

Re: [PATCH] workqueue: Better document teardown for delayed_work

[Tejun Heo]

Hello,

On Thu, Apr 03, 2025 at 10:31:56AM +0200, Philipp Stanner wrote:
> destroy_workqueue() does not ensure that non-pending work submitted with
> queue_delayed_work() gets cancelled. The caller has to ensure that
> manually.
> 
> Add this information about delayed_work in destroy_workqueue()'s
> docstring.
> 
> Signed-off-by: Philipp Stanner <phasta@kernel.org>
> ---
> Hi,
> 
> I have seen this WARN_ON [1] fire in my code for testing the DRM GPU
> Scheduler, where a (non-delayed) work_item from workqueue A submits
> delayed_work to workqueue B [2].
> 
> From my experience so far and reading the documentation, I didn't expect
> this to happen.
> 
> Assuming this is wanted behavior (?), I propose documenting this more
> explicitly. Or could it be possible to modify destroy_workqueue() so
> that it takes care of submitted delayed_work()?

This is definitely not a "wanted" behavior. The problem is that delayed work
items are only linked on the timer side and we don't have a way to list all
timers that are queued for work items on a specific workqueue, and there's
no way of adding that without incurring extra overhead. Maybe that'd be a
worthwhile trade-off to make, I don't know.

Can you please fortify the text a bit with the fact that this isn't a
desirable behavior but workqueue currently doesn't have a way of locating
the delayed timers queued on its behalf?

Thanks.

-- 
tejun