Skip to contentSkip to conversation

doc: add stack mempool guide

PATCH New Gage Eads 3 participants 9 messages Aug 11, 2020 – Oct 8, 2020

lore
Share & tools
lore

Gage Eads

author
#0 lore raw

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
index bbd02fd81..a0e55467e 100644
@@ -14,3 +14,4 @@ application through the mempool API.
     octeontx
     octeontx2
     ring
+    stack
doc/guides/mempool/stack.rst new file +38 -0
new file mode 100644
index 000000000..3baa774f3
@@ -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
index e3e1f940b..6f3c0067f 100644
@@ -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
index 8fe8804e3..3097cab0c 100644
@@ -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
author
#1 lore raw

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
index bbd02fd81..a0e55467e 100644
@@ -14,3 +14,4 @@ application through the mempool API.
     octeontx
     octeontx2
     ring
+    stack
doc/guides/mempool/stack.rst new file +38 -0
new file mode 100644
index 000000000..3baa774f3
@@ -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
index e3e1f940b..6f3c0067f 100644
@@ -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
index 8fe8804e3..3097cab0c 100644
@@ -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
author
#2 lore raw

PATCH v3 1/1 doc: add stack mempool guide

In reply to Gage Eads

This 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
index bbd02fd81..a0e55467e 100644
@@ -14,3 +14,4 @@ application through the mempool API.
     octeontx
     octeontx2
     ring
+    stack
doc/guides/mempool/stack.rst new file +38 -0
new file mode 100644
index 000000000..bdf19cf04
@@ -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
index e3e1f940b..6f3c0067f 100644
@@ -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
index 8fe8804e3..3097cab0c 100644
@@ -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
#3 lore raw

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.

---
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
index bbd02fd81..a0e55467e 100644
@@ -14,3 +14,4 @@ application through the mempool API.
     octeontx
     octeontx2
     ring
+    stack
doc/guides/mempool/stack.rst new file +1 -0
new file mode 100644
index 000000000..bdf19cf04
@@ -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
index e3e1f940b..6f3c0067f 100644
@@ -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
index 8fe8804e3..3097cab0c 100644
@@ -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
author
#4 lore raw

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 LIFO

behavior

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

#5 lore raw

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 LIFO

behavior

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

author
#6 lore raw

PATCH v4 1/1 doc: add stack mempool guide

In reply to Gage Eads

This 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
index bbd02fd81..a0e55467e 100644
@@ -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
index f0bdcd3be..890535eb2 100644
@@ -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
index 8fe8804e3..3097cab0c 100644
@@ -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