doc: add stack mempool guide
PATCH 1/1 doc: add stack mempool guide
--- doc/guides/mempool/index.rst | 1 + doc/guides/mempool/stack.rst | 38 +++++++++++++++++++++++++++++++++++ doc/guides/prog_guide/mempool_lib.rst | 2 ++ doc/guides/prog_guide/stack_lib.rst | 4 ++++ 4 files changed, 45 insertions(+) create mode 100644 doc/guides/mempool/stack.rst
doc/guides/mempool/index.rst +1 -0
@@ -14,3 +14,4 @@ application through the mempool API. octeontx octeontx2 ring + stack
doc/guides/mempool/stack.rst new file +38 -0
@@ -0,0 +1,38 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2020 Intel Corporation. + +Stack Mempool Driver +=================== + +**rte_mempool_stack** is a pure software mempool driver based on the +``rte_stack`` DPDK library. A stack-based mempool is often better suited to +packet-processing workloads than a ring-based mempool, since its LIFO behavior +results in better temporal locality and a minimal memory footprint even if the +mempool is over-provisioned. + +The following modes of operation are available for the stack mempool driver and +can be selected as described in :ref:`Mempool_Handlers`: + +- ``stack`` + + The underlying **rte_stack** operates in standard (lock-based) mode. + For more information please refer to :ref:`Stack_Library_Std_Stack`. + +- ``lf_stack`` + + The underlying **rte_stack** operates in lock-free mode. For more + information please refer to :ref:`Stack_Library_LF_Stack`. + +The standard stack outperforms the lock-free stack on average, however the +standard stack is non-preemptive: if a mempool user is preempted while holding +the stack lock, that thread will block all other mempool accesses until it +returns and releases the lock. As a result, an application using the standard +stack whose threads can be preempted can suffer from brief, infrequent +performance hiccups. + +The lock-free stack, by design, is not susceptible to this problem; one thread can +be preempted at any point during a push or pop operation and will not impede +the progress of any other thread. + +For a more detailed description of the stack implementations, please refer to +:doc:`../prog_guide/stack_lib`.
doc/guides/prog_guide/mempool_lib.rst +2 -0
@@ -105,6 +105,8 @@ These user-owned caches can be explicitly passed to ``rte_mempool_generic_put()` The ``rte_mempool_default_cache()`` call returns the default internal cache if any. In contrast to the default caches, user-owned caches can be used by unregistered non-EAL threads too. +.. _Mempool_Handlers: + Mempool Handlers ------------------------
doc/guides/prog_guide/stack_lib.rst +4 -0
@@ -28,6 +28,8 @@ Implementation The library supports two types of stacks: standard (lock-based) and lock-free. Both types use the same set of interfaces, but their implementations differ. +.. _Stack_Library_Std_Stack: + Lock-based Stack ----------------
@@ -35,6 +37,8 @@ The lock-based stack consists of a contiguous array of pointers, a current index, and a spinlock. Accesses to the stack are made multi-thread safe by the spinlock. +.. _Stack_Library_LF_Stack: + Lock-free Stack ------------------
Signature · 1 line
2.13.6
PATCH 1/1 doc: add stack mempool guide
This guide describes the two stack modes, their tradeoffs, and (via a reference to the mempool guide) how to enable them.
---
v2: Added commit description
doc/guides/mempool/index.rst | 1 + doc/guides/mempool/stack.rst | 38 +++++++++++++++++++++++++++++++++++ doc/guides/prog_guide/mempool_lib.rst | 2 ++ doc/guides/prog_guide/stack_lib.rst | 4 ++++ 4 files changed, 45 insertions(+) create mode 100644 doc/guides/mempool/stack.rst
doc/guides/mempool/index.rst +1 -0
@@ -14,3 +14,4 @@ application through the mempool API. octeontx octeontx2 ring + stack
doc/guides/mempool/stack.rst new file +38 -0
@@ -0,0 +1,38 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2020 Intel Corporation. + +Stack Mempool Driver +=================== + +**rte_mempool_stack** is a pure software mempool driver based on the +``rte_stack`` DPDK library. A stack-based mempool is often better suited to +packet-processing workloads than a ring-based mempool, since its LIFO behavior +results in better temporal locality and a minimal memory footprint even if the +mempool is over-provisioned. + +The following modes of operation are available for the stack mempool driver and +can be selected as described in :ref:`Mempool_Handlers`: + +- ``stack`` + + The underlying **rte_stack** operates in standard (lock-based) mode. + For more information please refer to :ref:`Stack_Library_Std_Stack`. + +- ``lf_stack`` + + The underlying **rte_stack** operates in lock-free mode. For more + information please refer to :ref:`Stack_Library_LF_Stack`. + +The standard stack outperforms the lock-free stack on average, however the +standard stack is non-preemptive: if a mempool user is preempted while holding +the stack lock, that thread will block all other mempool accesses until it +returns and releases the lock. As a result, an application using the standard +stack whose threads can be preempted can suffer from brief, infrequent +performance hiccups. + +The lock-free stack, by design, is not susceptible to this problem; one thread can +be preempted at any point during a push or pop operation and will not impede +the progress of any other thread. + +For a more detailed description of the stack implementations, please refer to +:doc:`../prog_guide/stack_lib`.
doc/guides/prog_guide/mempool_lib.rst +2 -0
@@ -105,6 +105,8 @@ These user-owned caches can be explicitly passed to ``rte_mempool_generic_put()` The ``rte_mempool_default_cache()`` call returns the default internal cache if any. In contrast to the default caches, user-owned caches can be used by unregistered non-EAL threads too. +.. _Mempool_Handlers: + Mempool Handlers ------------------------
doc/guides/prog_guide/stack_lib.rst +4 -0
@@ -28,6 +28,8 @@ Implementation The library supports two types of stacks: standard (lock-based) and lock-free. Both types use the same set of interfaces, but their implementations differ. +.. _Stack_Library_Std_Stack: + Lock-based Stack ----------------
@@ -35,6 +37,8 @@ The lock-based stack consists of a contiguous array of pointers, a current index, and a spinlock. Accesses to the stack are made multi-thread safe by the spinlock. +.. _Stack_Library_LF_Stack: + Lock-free Stack ------------------
Signature · 1 line
2.13.6
PATCH v3 1/1 doc: add stack mempool guide
In reply to Gage EadsThis guide describes the two stack modes, their tradeoffs, and (via a reference to the mempool guide) how to enable them.
---
v3: Fixed "Title underline too short" warning
v2: Added commit description
doc/guides/mempool/index.rst | 1 + doc/guides/mempool/stack.rst | 38 +++++++++++++++++++++++++++++++++++ doc/guides/prog_guide/mempool_lib.rst | 2 ++ doc/guides/prog_guide/stack_lib.rst | 4 ++++ 4 files changed, 45 insertions(+) create mode 100644 doc/guides/mempool/stack.rst
doc/guides/mempool/index.rst +1 -0
@@ -14,3 +14,4 @@ application through the mempool API. octeontx octeontx2 ring + stack
doc/guides/mempool/stack.rst new file +38 -0
@@ -0,0 +1,38 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2020 Intel Corporation. + +Stack Mempool Driver +==================== + +**rte_mempool_stack** is a pure software mempool driver based on the +``rte_stack`` DPDK library. A stack-based mempool is often better suited to +packet-processing workloads than a ring-based mempool, since its LIFO behavior +results in better temporal locality and a minimal memory footprint even if the +mempool is over-provisioned. + +The following modes of operation are available for the stack mempool driver and +can be selected as described in :ref:`Mempool_Handlers`: + +- ``stack`` + + The underlying **rte_stack** operates in standard (lock-based) mode. + For more information please refer to :ref:`Stack_Library_Std_Stack`. + +- ``lf_stack`` + + The underlying **rte_stack** operates in lock-free mode. For more + information please refer to :ref:`Stack_Library_LF_Stack`. + +The standard stack outperforms the lock-free stack on average, however the +standard stack is non-preemptive: if a mempool user is preempted while holding +the stack lock, that thread will block all other mempool accesses until it +returns and releases the lock. As a result, an application using the standard +stack whose threads can be preempted can suffer from brief, infrequent +performance hiccups. + +The lock-free stack, by design, is not susceptible to this problem; one thread can +be preempted at any point during a push or pop operation and will not impede +the progress of any other thread. + +For a more detailed description of the stack implementations, please refer to +:doc:`../prog_guide/stack_lib`.
doc/guides/prog_guide/mempool_lib.rst +2 -0
@@ -105,6 +105,8 @@ These user-owned caches can be explicitly passed to ``rte_mempool_generic_put()` The ``rte_mempool_default_cache()`` call returns the default internal cache if any. In contrast to the default caches, user-owned caches can be used by unregistered non-EAL threads too. +.. _Mempool_Handlers: + Mempool Handlers ------------------------
doc/guides/prog_guide/stack_lib.rst +4 -0
@@ -28,6 +28,8 @@ Implementation The library supports two types of stacks: standard (lock-based) and lock-free. Both types use the same set of interfaces, but their implementations differ. +.. _Stack_Library_Std_Stack: + Lock-based Stack ----------------
@@ -35,6 +37,8 @@ The lock-based stack consists of a contiguous array of pointers, a current index, and a spinlock. Accesses to the stack are made multi-thread safe by the spinlock. +.. _Stack_Library_LF_Stack: + Lock-free Stack ------------------
Signature · 1 line
2.13.6
Hi Gage,
Quoted 32 lines · Gage Eads
This guide describes the two stack modes, their tradeoffs, and (via a reference to the mempool guide) how to enable them.
Signed-off-by Gage Eads <[email protected]>---
v3: Fixed "Title underline too short" warningv2: Added commit description
doc/guides/mempool/index.rst | 1 + doc/guides/mempool/stack.rst | 38 +++++++++++++++++++++++++++++++++++ doc/guides/prog_guide/mempool_lib.rst | 2 ++ doc/guides/prog_guide/stack_lib.rst | 4 ++++ 4 files changed, 45 insertions(+) create mode 100644 doc/guides/mempool/stack.rstdoc/guides/mempool/index.rst +1
-0@@ -14,3 +14,4 @@ application through the mempool API. octeontx octeontx2 ring + stackdoc/guides/mempool/stack.rst new file +1
-0@@ -0,0 +1,38 @@ +.. SPDX-License-Identifier: BSD-3-Clause
doc/guides/mempool/stack.rst line 11
Quoted 10 lines
doc/guides/mempool/stack.rst new file +10
-0+ Copyright(c) 2020 Intel Corporation. + +Stack Mempool Driver +==================== + +**rte_mempool_stack** is a pure software mempool driver based on the +``rte_stack`` DPDK library. A stack-based mempool is often better suited to +packet-processing workloads than a ring-based mempool, since its LIFO behavior +results in better temporal locality and a minimal memory footprint even if the +mempool is over-provisioned.
Would it make sense to give an example of a use-case where the stack driver should be used in place of the standard ring-based one?
In most run-to-completion applications, the mbufs stay in per-core caches, so changing the mempool driver won't have a big impact. However, I suspect that for applications using a pipeline model (ex: rx on core0, tx on core1), the stack model would be more efficient. Is it something that you measured? If yes, it would be useful to explain this in the documentation.
Quoted 65 lines
doc/guides/mempool/stack.rst new file +27
-0+ +The following modes of operation are available for the stack mempool driver and +can be selected as described in :ref:`Mempool_Handlers`: + +- ``stack`` + + The underlying **rte_stack** operates in standard (lock-based) mode. + For more information please refer to :ref:`Stack_Library_Std_Stack`. + +- ``lf_stack`` + + The underlying **rte_stack** operates in lock-free mode. For more + information please refer to :ref:`Stack_Library_LF_Stack`. + +The standard stack outperforms the lock-free stack on average, however the +standard stack is non-preemptive: if a mempool user is preempted while holding +the stack lock, that thread will block all other mempool accesses until it +returns and releases the lock. As a result, an application using the standard +stack whose threads can be preempted can suffer from brief, infrequent +performance hiccups. + +The lock-free stack, by design, is not susceptible to this problem; one thread can +be preempted at any point during a push or pop operation and will not impede +the progress of any other thread. + +For a more detailed description of the stack implementations, please refer to +:doc:`../prog_guide/stack_lib`.doc/guides/prog_guide/mempool_lib.rst +2
-0@@ -105,6 +105,8 @@ These user-owned caches can be explicitly passed to ``rte_mempool_generic_put()` The ``rte_mempool_default_cache()`` call returns the default internal cache if any. In contrast to the default caches, user-owned caches can be used by unregistered non-EAL threads too. +.. _Mempool_Handlers: + Mempool Handlers ------------------------doc/guides/prog_guide/stack_lib.rst +4
-0@@ -28,6 +28,8 @@ Implementation The library supports two types of stacks: standard (lock-based) and lock-free. Both types use the same set of interfaces, but their implementations differ. +.. _Stack_Library_Std_Stack: + Lock-based Stack ----------------@@ -35,6 +37,8 @@ The lock-based stack consists of a contiguous array of pointers, a current index, and a spinlock. Accesses to the stack are made multi-thread safe by the spinlock. +.. _Stack_Library_LF_Stack: + Lock-free Stack ------------------Signature · 1 line
2.13.6
Hi Olivier,
<snip>
Quoted 13 lines
doc/guides/mempool/stack.rst
Quoted 6 lines
doc/guides/mempool/stack.rst new file +6
-0+Stack Mempool Driver +==================== + +**rte_mempool_stack** is a pure software mempool driver based on the +``rte_stack`` DPDK library. A stack-based mempool is often better suited to +packet-processing workloads than a ring-based mempool, since its LIFObehavior
doc/guides/mempool/stack.rst line 11
Quoted 2 lines
doc/guides/mempool/stack.rst new file +2
-0+results in better temporal locality and a minimal memory footprint even if the +mempool is over-provisioned.Would it make sense to give an example of a use-case where the stack driver should be used in place of the standard ring-based one?
Quoted 7 lines
In most run-to-completion applications, the mbufs stay in per-core caches, so changing the mempool driver won't have a big impact. However, I suspect that for applications using a pipeline model (ex: rx on core0, tx on core1), the stack model would be more efficient. Is it something that you measured? If yes, it would be useful to explain this in the documentation.
Good point, I was overlooking the impact of the per-core caches. I've seen data showing better overall packet throughput with the stack mempool, and indeed that was a pipelined application. How about this re-write?
"
**rte_mempool_stack** is a pure software mempool driver based on the ``rte_stack`` DPDK library. For run-to-completion workloads with sufficiently large per-lcore caches, the mbufs will likely stay in the per-lcore caches and the mempool type (ring, stack, etc.) will have a negligible impact on performance. However a stack-based mempool is often better suited to pipelined packet-processing workloads (which allocate and free mbufs on different lcores) than a ring-based mempool, since its LIFO behavior results in better temporal locality and a minimal memory footprint even if the mempool is over-provisioned. Users are encouraged to benchmark with multiple mempool types to determine which works best for their specific application. "
Thanks,
Gage
Hi Gage,
Quoted 29 lines · Gage
Hi Olivier,
<snip>
Quoted 13 lines
doc/guides/mempool/stack.rst
Quoted 6 lines
doc/guides/mempool/stack.rst new file +6
-0+Stack Mempool Driver +==================== + +**rte_mempool_stack** is a pure software mempool driver based on the +``rte_stack`` DPDK library. A stack-based mempool is often better suited to +packet-processing workloads than a ring-based mempool, since its LIFObehavior
doc/guides/mempool/stack.rst line 11
Quoted 2 lines
doc/guides/mempool/stack.rst new file +2
-0+results in better temporal locality and a minimal memory footprint even if the +mempool is over-provisioned.Would it make sense to give an example of a use-case where the stack driver should be used in place of the standard ring-based one?
Quoted 7 lines
In most run-to-completion applications, the mbufs stay in per-core caches, so changing the mempool driver won't have a big impact. However, I suspect that for applications using a pipeline model (ex: rx on core0, tx on core1), the stack model would be more efficient. Is it something that you measured? If yes, it would be useful to explain this in the documentation.
Good point, I was overlooking the impact of the per-core caches. I've seen data showing better overall packet throughput with the stack mempool, and indeed that was a pipelined application. How about this re-write?
Quoted 11 lines
"
**rte_mempool_stack** is a pure software mempool driver based on the ``rte_stack`` DPDK library. For run-to-completion workloads with sufficiently large per-lcore caches, the mbufs will likely stay in the per-lcore caches and the mempool type (ring, stack, etc.) will have a negligible impact on performance. However a stack-based mempool is often better suited to pipelined packet-processing workloads (which allocate and free mbufs on different lcores) than a ring-based mempool, since its LIFO behavior results in better temporal locality and a minimal memory footprint even if the mempool is over-provisioned. Users are encouraged to benchmark with multiple mempool types to determine which works best for their specific application. "
Yes, this is clear, thanks!
Olivier
PATCH v4 1/1 doc: add stack mempool guide
In reply to Gage EadsThis guide describes the two stack modes, their tradeoffs, and (via a reference to the mempool guide) how to enable them.
---
v4: Expanded first paragraph in stack.rst per Olivier's feedback
v3: Fixed "Title underline too short" warning
v2: Added commit description
doc/guides/mempool/index.rst | 1 + doc/guides/mempool/stack.rst | 43 +++++++++++++++++++++++++++++++++++ doc/guides/prog_guide/mempool_lib.rst | 2 ++ doc/guides/prog_guide/stack_lib.rst | 4 ++++ 4 files changed, 50 insertions(+) create mode 100644 doc/guides/mempool/stack.rst
doc/guides/mempool/index.rst +1 -0
@@ -14,3 +14,4 @@ application through the mempool API. octeontx octeontx2 ring + stack
doc/guides/mempool/stack.rst new file +43 -0
43 lines not on this page · raw message
doc/guides/prog_guide/mempool_lib.rst +2 -0
@@ -104,6 +104,8 @@ These user-owned caches can be explicitly passed to ``rte_mempool_generic_put()` The ``rte_mempool_default_cache()`` call returns the default internal cache if any. In contrast to the default caches, user-owned caches can be used by unregistered non-EAL threads too. +.. _Mempool_Handlers: + Mempool Handlers ------------------------
doc/guides/prog_guide/stack_lib.rst +4 -0
@@ -28,6 +28,8 @@ Implementation The library supports two types of stacks: standard (lock-based) and lock-free. Both types use the same set of interfaces, but their implementations differ. +.. _Stack_Library_Std_Stack: + Lock-based Stack ----------------
@@ -35,6 +37,8 @@ The lock-based stack consists of a contiguous array of pointers, a current index, and a spinlock. Accesses to the stack are made multi-thread safe by the spinlock. +.. _Stack_Library_LF_Stack: + Lock-free Stack ------------------
Signature · 1 line
2.13.6
Quoted 4 lines · Gage Eads
This guide describes the two stack modes, their tradeoffs, and (via a reference to the mempool guide) how to enable them.
Signed-off-by Gage Eads <[email protected]>
David Marchand
AppliedQuoted 8 lines · Olivier Matz
Quoted 4 lines · Gage Eads
This guide describes the two stack modes, their tradeoffs, and (via a reference to the mempool guide) how to enable them.
Signed-off-by Gage Eads <[email protected]>Reviewed-by Olivier Matz <[email protected]>
Applied, thanks.
Signature · 1 line
David Marchand