[<prev] [next>] [<thread-prev] [day] [month] [year] [list]
Message-ID: <a1704f1a-f05b-4798-a3a4-a1d35d7282fd@redhat.com>
Date: Fri, 9 Feb 2024 11:46:35 -0500
From: Waiman Long <longman@...hat.com>
To: Jonathan Corbet <corbet@....net>, Tejun Heo <tj@...nel.org>
Cc: Lai Jiangshan <jiangshanlai@...il.com>, linux-kernel@...r.kernel.org
Subject: Re: [PATCH] workqueue: Fix kernel-doc comment of unplug_oldest_pwq()
On 2/9/24 11:36, Jonathan Corbet wrote:
> Tejun Heo <tj@...nel.org> writes:
>
>> (cc'ing Jonathan and quoting whole body)
>>
>> I'm not necessarily against the patch but at least from in-code
>> documentation POV the diagram being in the function comment seems better.
>> Jonathan, do you happen to know a better way to address this?
> So I went to reproduce this problem, but it seems that it's hidden away
> in some branch and not in linux-next. So I'll have to guess without
> testing my solution, but...
>
>> On Fri, Feb 09, 2024 at 09:58:50AM -0500, Waiman Long wrote:
>>> It turns out that it is not a good idea to put an ASCII diagram in the
>>> kernel-doc comment of unplug_oldest_pwq() as the tool puts out warnings
>>> about its format and will likely render it illegible anyway. Break the
>>> ASCII diagram out into its own comment block inside the function to
>>> avoid this problem.
>>>
>>> Signed-off-by: Waiman Long <longman@...hat.com>
>>> ---
>>> kernel/workqueue.c | 32 ++++++++++++++++++--------------
>>> 1 file changed, 18 insertions(+), 14 deletions(-)
>>>
>>> diff --git a/kernel/workqueue.c b/kernel/workqueue.c
>>> index cd2c6edc5c66..f622f535bc00 100644
>>> --- a/kernel/workqueue.c
>>> +++ b/kernel/workqueue.c
>>> @@ -1790,25 +1790,29 @@ static bool pwq_activate_first_inactive(struct pool_workqueue *pwq, bool fill)
>>> * unplug_oldest_pwq - restart an oldest plugged pool_workqueue
>>> * @wq: workqueue_struct to be restarted
>>> *
>>> - * pwq's are linked into wq->pwqs with the oldest first. For ordered
>>> - * workqueues, only the oldest pwq is unplugged, the others are plugged to
>>> - * suspend execution until the oldest one is drained. When this happens, the
>>> - * next oldest one (first plugged pwq in iteration) will be unplugged to
>>> - * restart work item execution to ensure proper work item ordering.
>>> - *
>>> - * dfl_pwq --------------+ [P] - plugged
>>> - * |
>>> - * v
>>> - * pwqs -> A -> B [P] -> C [P] (newest)
>>> - * | | |
>>> - * 1 3 5
>>> - * | | |
>>> - * 2 4 6
>>> + * This function should only be called for ordered workqueues where only the
> The problem here is that you have a literal block without marking it as
> such. If you were to format it as:
>
>> * next oldest one (first plugged pwq in iteration) will be unplugged to
>> * restart work item execution to ensure proper work item ordering::
>> *
>> * dfl_pwq --------------+ [P] - plugged
>> * |
>> * v
>> * pwqs -> A -> B [P] -> C [P] (newest)
>> * | | |
>> * 1 3 5
>> * | | |
>> * 2 4 6
>> *
>> * This function should only be called for ordered workqueues where only the
> ...it should work. The changes are the "::" after "ordering" and the
> blank line at the end of the block.
>
Thanks for the tip. I will update my patch to use the proper formatting
hint.
Cheers,
Longman
Powered by blists - more mailing lists