doc/guides/mempool/stack.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2020 Intel Corporation.
   3
   4 Stack Mempool Driver
   5 ====================
   6
   7 **rte_mempool_stack** is a pure software mempool driver based on the
   8 ``rte_stack`` DPDK library. For run-to-completion workloads with sufficiently
   9 large per-lcore caches, the mbufs will likely stay in the per-lcore caches and
  10 the mempool type (ring, stack, etc.) will have a negligible impact on
  11 performance. However a stack-based mempool is often better suited to pipelined
  12 packet-processing workloads (which allocate and free mbufs on different lcores)
  13 than a ring-based mempool, since its LIFO behavior results in better temporal
  14 locality and a minimal memory footprint even if the mempool is
  15 over-provisioned. Users are encouraged to benchmark with multiple mempool types
  16 to determine which works best for their specific application.
  17
  18 The following modes of operation are available for the stack mempool driver and
  19 can be selected as described in :ref:`Mempool_Handlers`:
  20
  21 - ``stack``
  22
  23   The underlying **rte_stack** operates in standard (lock-based) mode.
  24   For more information please refer to :ref:`Stack_Library_Std_Stack`.
  25
  26 - ``lf_stack``
  27
  28   The underlying **rte_stack** operates in lock-free mode. For more
  29   information please refer to :ref:`Stack_Library_LF_Stack`.
  30
  31 The standard stack outperforms the lock-free stack on average, however the
  32 standard stack is non-preemptive: if a mempool user is preempted while holding
  33 the stack lock, that thread will block all other mempool accesses until it
  34 returns and releases the lock. As a result, an application using the standard
  35 stack whose threads can be preempted can suffer from brief, infrequent
  36 performance hiccups.
  37
  38 The lock-free stack, by design, is not susceptible to this problem; one thread can
  39 be preempted at any point during a push or pop operation and will not impede
  40 the progress of any other thread.
  41
  42 For a more detailed description of the stack implementations, please refer to
  43 :doc:`../prog_guide/stack_lib`.