docs/core-api: Fix circular buffer examples
PATCH 1/1 docs/core-api: Fix circular buffer examples
From: Carlos Bilbao <[email protected]>
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.
--- Documentation/core-api/circular-buffers.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/core-api/circular-buffers.rst +2 -2
@@ -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);
Signature · 1 line
2.43.0
+CC David and Paul, who are the authors of this doc.
Quoted 37 lines · Carlos Bilbao
From: Carlos Bilbao <[email protected]>
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 usebuffer->headandbuffer->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 <[email protected]>--- Documentation/core-api/circular-buffers.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)Documentation/core-api/circular-buffers.rst +2
-2@@ -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);Signature · 1 line
2.43.0
Thanks, Akira
Quoted 12 lines · Akira Yokosawa
+CC David and Paul, who are the authors of this doc.
Quoted 9 lines · Carlos Bilbao
From: Carlos Bilbao <[email protected]>
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 usebuffer->headandbuffer->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 <[email protected]>
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?
Thanx, Paul
Quoted 31 lines
Quoted 28 lines
--- Documentation/core-api/circular-buffers.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)Documentation/core-api/circular-buffers.rst +2
-2@@ -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);Signature · 1 line
2.43.0Thanks, Akira
Hello,
Quoted 12 lines · Paul E. McKenney
Quoted 11 lines · Akira Yokosawa
+CC David and Paul, who are the authors of this doc.
Quoted 8 lines · Carlos Bilbao
From: Carlos Bilbao <[email protected]>
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 usebuffer->headandbuffer->tail, so it's a struct. Use buffer->vals[head] and buffer->vals[tail] instead to match the intended layout.>
Quoted 8 lines
Quoted 1 line
Quoted 1 line
Signed-off-by Carlos Bilbao <[email protected]>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()andCIRC_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 <[email protected]>
Date: Wed Mar 24 09:43:00 2010 +0000
Document Linux's circular buffering capabilities
Document the circular buffering capabilities available in Linux.
Quoted 33 lines
Thanx, Paul
Quoted 30 lines
Quoted 28 lines
--- Documentation/core-api/circular-buffers.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)Documentation/core-api/circular-buffers.rst +2
-2@@ -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);Signature · 1 line
2.43.0Thanks, Akira
Thanks,
Carlos
Quoted 33 lines · Carlos Bilbao
Hello,
Quoted 12 lines · Paul E. McKenney
Quoted 11 lines · Akira Yokosawa
+CC David and Paul, who are the authors of this doc.
Quoted 8 lines · Carlos Bilbao
From: Carlos Bilbao <[email protected]>
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 usebuffer->headandbuffer->tail, so it's a struct. Use buffer->vals[head] and buffer->vals[tail] instead to match the intended layout.>Quoted 8 lines
Quoted 1 line
Quoted 1 line
Signed-off-by Carlos Bilbao <[email protected]>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()andCIRC_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 <[email protected]>
Date: Wed Mar 24 09:43:00 2010 +0000Document Linux's circular buffering capabilities
Quoted 7 lines
Document the circular buffering capabilities available in Linux.
Signed-off-by David Howells <[email protected]>Signed-off-by Paul E. McKenney <[email protected]>Reviewed-by Randy Dunlap <[email protected]>Reviewed-by Stefan Richter <[email protected]>Signed-off-by Linus Torvalds <[email protected]>
Please understand that I am not arguing for no change, and that I do appreciate your attention to detail and your willingness to propose an actual change.
In this sentence in the original: "The producer will look something like this", the words "something like" are important, as in the following is pseudocode rather than code that can be built. You appear to be looking to make this be actual code, which would be a good thing. Except that we have this:
struct circ_buf {
char *buf;
int head;
int tail;
};As you can see, there is no ->vals member, which is likely to look silly to some future reader, just as the conflict between "buffer->size" on the one hand and "buffer[head]" on the other looked silly to you, and rightly so. And both you and that potential future reader would be quite justified in their judging the pseudo code as being silly.
So if we are going to change this, why not bite the bullet and make it be real code that lives within the confines of the circ_buf structure? Or, alternatively, that creates its own structure on the other? Either approach will be a larger change, but the result will be more helpful to a larger fraction of the future readers.
One approach would be to look for uses of the circ_buf structure, CIRC_SPACE(), and CIRC_CNT() in the kernel and create an example based on a simple use case.
Would you be willing to take this on?
Thanx, Paul
Quoted 29 lines
Quoted 16 lines
Quoted 16 lines
Quoted 16 lines
--- Documentation/core-api/circular-buffers.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)Documentation/core-api/circular-buffers.rst +1
-1@@ -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) {Quoted 8 lines
Quoted 8 lines
Quoted 6 lines
Documentation/core-api/circular-buffers.rst +1
-1/* extract one item from the buffer */ - struct item *item = buffer[tail]; + struct item *item = buffer->vals[tail]; consume_item(item);Signature · 1 line
2.43.0Thanks, Akira
Thanks,
Carlos