doc/guides/prog_guide/rcu_lib.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2019 Arm Limited.
   3
   4 .. _RCU_Library:
   5
   6 RCU Library
   7 ============
   8
   9 Lockless data structures provide scalability and determinism.
  10 They enable use cases where locking may not be allowed
  11 (for example real-time applications).
  12
  13 In the following sections, the term "memory" refers to memory allocated
  14 by typical APIs like malloc() or anything that is representative of
  15 memory, for example an index of a free element array.
  16
  17 Since these data structures are lockless, the writers and readers
  18 are accessing the data structures concurrently. Hence, while removing
  19 an element from a data structure, the writers cannot return the memory
  20 to the allocator, without knowing that the readers are not
  21 referencing that element/memory anymore. Hence, it is required to
  22 separate the operation of removing an element into two steps:
  23
  24 #. Delete: in this step, the writer removes the reference to the element from
  25    the data structure but does not return the associated memory to the
  26    allocator. This will ensure that new readers will not get a reference to
  27    the removed element. Removing the reference is an atomic operation.
  28
  29 #. Free (Reclaim): in this step, the writer returns the memory to the
  30    memory allocator only after knowing that all the readers have stopped
  31    referencing the deleted element.
  32
  33 This library helps the writer determine when it is safe to free the
  34 memory by making use of thread Quiescent State (QS).
  35
  36 What is Quiescent State
  37 -----------------------
  38
  39 Quiescent State can be defined as "any point in the thread execution where the
  40 thread does not hold a reference to shared memory". It is up to the application
  41 to determine its quiescent state.
  42
  43 Let us consider the following diagram:
  44
  45 .. _figure_quiescent_state:
  46
  47 .. figure:: img/rcu_general_info.*
  48
  49    Phases in the Quiescent State model.
  50
  51
  52 As shown in :numref:`figure_quiescent_state`, reader thread 1 accesses data
  53 structures D1 and D2. When it is accessing D1, if the writer has to remove an
  54 element from D1, the writer cannot free the memory associated with that
  55 element immediately. The writer can return the memory to the allocator only
  56 after the reader stops referencing D1. In other words, reader thread RT1 has
  57 to enter a quiescent state.
  58
  59 Similarly, since reader thread 2 is also accessing D1, the writer has to
  60 wait till thread 2 enters quiescent state as well.
  61
  62 However, the writer does not need to wait for reader thread 3 to enter
  63 quiescent state. Reader thread 3 was not accessing D1 when the delete
  64 operation happened. So, reader thread 1 will not have a reference to the
  65 deleted entry.
  66
  67 It can be noted that, the critical sections for D2 is a quiescent state
  68 for D1. i.e. for a given data structure Dx, any point in the thread execution
  69 that does not reference Dx is a quiescent state.
  70
  71 Since memory is not freed immediately, there might be a need for
  72 provisioning of additional memory, depending on the application requirements.
  73
  74 Factors affecting the RCU mechanism
  75 -----------------------------------
  76
  77 It is important to make sure that this library keeps the overhead of
  78 identifying the end of grace period and subsequent freeing of memory,
  79 to a minimum. The following explains how grace period and critical
  80 section affect this overhead.
  81
  82 The writer has to poll the readers to identify the end of grace period.
  83 Polling introduces memory accesses and wastes CPU cycles. The memory
  84 is not available for reuse during the grace period. Longer grace periods
  85 exasperate these conditions.
  86
  87 The length of the critical section and the number of reader threads
  88 is proportional to the duration of the grace period. Keeping the critical
  89 sections smaller will keep the grace period smaller. However, keeping the
  90 critical sections smaller requires additional CPU cycles (due to additional
  91 reporting) in the readers.
  92
  93 Hence, we need the characteristics of a small grace period and large critical
  94 section. This library addresses this by allowing the writer to do
  95 other work without having to block until the readers report their quiescent
  96 state.
  97
  98 RCU in DPDK
  99 -----------
 100
 101 For DPDK applications, the start and end of a ``while(1)`` loop (where no
 102 references to shared data structures are kept) act as perfect quiescent
 103 states. This will combine all the shared data structure accesses into a
 104 single, large critical section which helps keep the overhead on the
 105 reader side to a minimum.
 106
 107 DPDK supports a pipeline model of packet processing and service cores.
 108 In these use cases, a given data structure may not be used by all the
 109 workers in the application. The writer does not have to wait for all
 110 the workers to report their quiescent state. To provide the required
 111 flexibility, this library has a concept of a QS variable. The application
 112 can create one QS variable per data structure to help it track the
 113 end of grace period for each data structure. This helps keep the grace
 114 period to a minimum.
 115
 116 How to use this library
 117 -----------------------
 118
 119 The application must allocate memory and initialize a QS variable.
 120
 121 Applications can call ``rte_rcu_qsbr_get_memsize()`` to calculate the size
 122 of memory to allocate. This API takes a maximum number of reader threads,
 123 using this variable, as a parameter. Currently, a maximum of 1024 threads
 124 are supported.
 125
 126 Further, the application can initialize a QS variable using the API
 127 ``rte_rcu_qsbr_init()``.
 128
 129 Each reader thread is assumed to have a unique thread ID. Currently, the
 130 management of the thread ID (for example allocation/free) is left to the
 131 application. The thread ID should be in the range of 0 to
 132 maximum number of threads provided while creating the QS variable.
 133 The application could also use ``lcore_id`` as the thread ID where applicable.
 134
 135 The ``rte_rcu_qsbr_thread_register()`` API will register a reader thread
 136 to report its quiescent state. This can be called from a reader thread.
 137 A control plane thread can also call this on behalf of a reader thread.
 138 The reader thread must call ``rte_rcu_qsbr_thread_online()`` API to start
 139 reporting its quiescent state.
 140
 141 Some of the use cases might require the reader threads to make blocking API
 142 calls (for example while using eventdev APIs). The writer thread should not
 143 wait for such reader threads to enter quiescent state.  The reader thread must
 144 call ``rte_rcu_qsbr_thread_offline()`` API, before calling blocking APIs. It
 145 can call ``rte_rcu_qsbr_thread_online()`` API once the blocking API call
 146 returns.
 147
 148 The writer thread can trigger the reader threads to report their quiescent
 149 state by calling the API ``rte_rcu_qsbr_start()``. It is possible for multiple
 150 writer threads to query the quiescent state status simultaneously. Hence,
 151 ``rte_rcu_qsbr_start()`` returns a token to each caller.
 152
 153 The writer thread must call ``rte_rcu_qsbr_check()`` API with the token to
 154 get the current quiescent state status. Option to block till all the reader
 155 threads enter the quiescent state is provided. If this API indicates that
 156 all the reader threads have entered the quiescent state, the application
 157 can free the deleted entry.
 158
 159 The APIs ``rte_rcu_qsbr_start()`` and ``rte_rcu_qsbr_check()`` are lock free.
 160 Hence, they can be called concurrently from multiple writers even while
 161 running as worker threads.
 162
 163 The separation of triggering the reporting from querying the status provides
 164 the writer threads flexibility to do useful work instead of blocking for the
 165 reader threads to enter the quiescent state or go offline. This reduces the
 166 memory accesses due to continuous polling for the status.
 167
 168 The ``rte_rcu_qsbr_synchronize()`` API combines the functionality of
 169 ``rte_rcu_qsbr_start()`` and blocking ``rte_rcu_qsbr_check()`` into a single
 170 API. This API triggers the reader threads to report their quiescent state and
 171 polls till all the readers enter the quiescent state or go offline. This API
 172 does not allow the writer to do useful work while waiting and introduces
 173 additional memory accesses due to continuous polling.
 174
 175 The reader thread must call ``rte_rcu_qsbr_thread_offline()`` and
 176 ``rte_rcu_qsbr_thread_unregister()`` APIs to remove itself from reporting its
 177 quiescent state. The ``rte_rcu_qsbr_check()`` API will not wait for this reader
 178 thread to report the quiescent state status anymore.
 179
 180 The reader threads should call ``rte_rcu_qsbr_quiescent()`` API to indicate that
 181 they entered a quiescent state. This API checks if a writer has triggered a
 182 quiescent state query and update the state accordingly.
 183
 184 The ``rte_rcu_qsbr_lock()`` and ``rte_rcu_qsbr_unlock()`` are empty functions.
 185 However, when ``CONFIG_RTE_LIBRTE_RCU_DEBUG`` is enabled, these APIs aid
 186 in debugging issues. One can mark the access to shared data structures on the
 187 reader side using these APIs. The ``rte_rcu_qsbr_quiescent()`` will check if
 188 all the locks are unlocked.