From: Honnappa Nagarahalli <honnappa.nagarahalli@arm.com>
To: olivier.matz@6wind.com, honnappa.nagarahalli@arm.com
Cc: david.marchand@redhat.com, dev@dpdk.org, gavin.hu@arm.com, nd@arm.com
Subject: [dpdk-dev] [PATCH 2/2] doc: change prog guide to reflect rte_ring_xxx_elem apis
Date: Thu, 30 Jan 2020 21:59:29 -0600 [thread overview]
Message-ID: <20200131035929.2576-2-honnappa.nagarahalli@arm.com> (raw)
In-Reply-To: <20200131035929.2576-1-honnappa.nagarahalli@arm.com>
Changed the rte_ring chapter in programmer's guide to reflect
the addition of rte_ring_xxx_elem APIs. References to pointers
as ring elements is changed to generic term 'objects'.
Signed-off-by: Honnappa Nagarahalli <honnappa.nagarahalli@arm.com>
Reviewed-by: Gavin Hu <gavin.hu@arm.com>
---
doc/guides/prog_guide/ring_lib.rst | 16 +++++++++-------
1 file changed, 9 insertions(+), 7 deletions(-)
diff --git a/doc/guides/prog_guide/ring_lib.rst b/doc/guides/prog_guide/ring_lib.rst
index 5a9b6137e..8cb2b2dd4 100644
--- a/doc/guides/prog_guide/ring_lib.rst
+++ b/doc/guides/prog_guide/ring_lib.rst
@@ -11,7 +11,9 @@ Instead of having a linked list of infinite size, the rte_ring has the following
* FIFO
-* Maximum size is fixed, the pointers are stored in a table
+* Maximum size is fixed, the objects are stored in a table
+
+* Objects can be pointers or elements of multiple of 4 byte size
* Lockless implementation
@@ -29,19 +31,19 @@ Instead of having a linked list of infinite size, the rte_ring has the following
The advantages of this data structure over a linked list queue are as follows:
-* Faster; only requires a single Compare-And-Swap instruction of sizeof(void \*) instead of several double-Compare-And-Swap instructions.
+* Faster; only requires a single 32 bit Compare-And-Swap instruction instead of several pointer size Compare-And-Swap instructions.
* Simpler than a full lockless queue.
* Adapted to bulk enqueue/dequeue operations.
- As pointers are stored in a table, a dequeue of several objects will not produce as many cache misses as in a linked queue.
+ As objects are stored in a table, a dequeue of several objects will not produce as many cache misses as in a linked queue.
Also, a bulk dequeue of many objects does not cost more than a dequeue of a simple object.
The disadvantages:
* Size is fixed
-* Having many rings costs more in terms of memory than a linked list queue. An empty ring contains at least N pointers.
+* Having many rings costs more in terms of memory than a linked list queue. An empty ring contains at least N objects.
A simplified representation of a Ring is shown in with consumer and producer head and tail pointers to objects stored in the data structure.
@@ -125,7 +127,7 @@ Enqueue Second Step
The second step is to modify *ring->prod_head* in ring structure to point to the same location as prod_next.
-A pointer to the added object is copied in the ring (obj4).
+The added object is copied in the ring (obj4).
.. _figure_ring-enqueue2:
@@ -178,7 +180,7 @@ Dequeue Second Step
The second step is to modify ring->cons_head in the ring structure to point to the same location as cons_next.
-The pointer to the dequeued object (obj1) is copied in the pointer given by the user.
+The dequeued object (obj1) is copied in the pointer given by the user.
.. _figure_ring-dequeue2:
@@ -298,7 +300,7 @@ Modulo 32-bit Indexes
In the preceding figures, the prod_head, prod_tail, cons_head and cons_tail indexes are represented by arrows.
In the actual implementation, these values are not between 0 and size(ring)-1 as would be assumed.
-The indexes are between 0 and 2^32 -1, and we mask their value when we access the pointer table (the ring itself).
+The indexes are between 0 and 2^32 -1, and we mask their value when we access the object table (the ring itself).
32-bit modulo also implies that operations on indexes (such as, add/subtract) will automatically do 2^32 modulo
if the result overflows the 32-bit number range.
--
2.17.1
next prev parent reply other threads:[~2020-01-31 3:59 UTC|newest]
Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-01-31 3:59 [dpdk-dev] [PATCH 1/2] lib/ring: fix documentation for " Honnappa Nagarahalli
2020-01-31 3:59 ` Honnappa Nagarahalli [this message]
2020-02-15 16:55 ` [dpdk-dev] [PATCH 2/2] doc: change prog guide to reflect " Thomas Monjalon
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200131035929.2576-2-honnappa.nagarahalli@arm.com \
--to=honnappa.nagarahalli@arm.com \
--cc=david.marchand@redhat.com \
--cc=dev@dpdk.org \
--cc=gavin.hu@arm.com \
--cc=nd@arm.com \
--cc=olivier.matz@6wind.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).