Re: [PATCH] docs/core-api: Fix circular buffer examples

[Carlos Bilbao <bilbao@vt.edu>]

Hello,

On 7/23/25 15:47, Paul E. McKenney wrote:
> On Mon, Jul 21, 2025 at 11:47:25AM +0900, Akira Yokosawa wrote:
>> +CC David and Paul, who are the authors of this doc.
>>
>> On Sun, 20 Jul 2025 11:02:43 -0500, Carlos Bilbao wrote:
>>> From: Carlos Bilbao <carlos.bilbao@kernel.org>
>>>
>>> Fix circular buffer usage in producer/consumer examples in
>>> circular-buffers.rst. They incorrectly access items using buffer[head] and
>>> buffer[tail], as if buffer was a flat array; but the examples also use
>>> buffer->head and buffer->tail, so it's a struct. Use buffer->vals[head] and
>>> buffer->vals[tail] instead to match the intended layout.>
>>>
>>> Signed-off-by: Carlos Bilbao <carlos.bilbao@kernel.org>
> Hello, Carlos, and thank you for your attention to detail!
>
> This one could likely use more help, as the last substantive change was
> more than ten years ago.
>
> But are you referring to a particular use of CIRC_SPACE() and CIRC_CNT()
> for this change?  If so, could you please identify it in the commit log?


No, it's just the uses of the structure. Take a look at the patch, you'll
see. The mistake was introduced in this commit:

commit 90fddabf5818367c6bd1fe1b256a10e01827862f
Author: David Howells <dhowells@redhat.com>
Date:   Wed Mar 24 09:43:00 2010 +0000

     Document Linux's circular buffering capabilities

     Document the circular buffering capabilities available in Linux.

     Signed-off-by: David Howells <dhowells@redhat.com>
     Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
     Reviewed-by: Randy Dunlap <rdunlap@xenotime.net>
     Reviewed-by: Stefan Richter <stefanr@s5r6.in-berlin.de>
     Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>


>
> 							Thanx, Paul
>
>>> ---
>>>   Documentation/core-api/circular-buffers.rst | 4 ++--
>>>   1 file changed, 2 insertions(+), 2 deletions(-)
>>>
>>> diff --git a/Documentation/core-api/circular-buffers.rst b/Documentation/core-api/circular-buffers.rst
>>> index 50966f66e398..b697915a2bd0 100644
>>> --- a/Documentation/core-api/circular-buffers.rst
>>> +++ b/Documentation/core-api/circular-buffers.rst
>>> @@ -161,7 +161,7 @@ The producer will look something like this::
>>>   
>>>   	if (CIRC_SPACE(head, tail, buffer->size) >= 1) {
>>>   		/* insert one item into the buffer */
>>> -		struct item *item = buffer[head];
>>> +		struct item *item = buffer->vals[head];
>>>   
>>>   		produce_item(item);
>>>   
>>> @@ -203,7 +203,7 @@ The consumer will look something like this::
>>>   	if (CIRC_CNT(head, tail, buffer->size) >= 1) {
>>>   
>>>   		/* extract one item from the buffer */
>>> -		struct item *item = buffer[tail];
>>> +		struct item *item = buffer->vals[tail];
>>>   
>>>   		consume_item(item);
>>>   
>>> -- 
>>> 2.43.0
>>          Thanks, Akira
>>

Thanks,

Carlos