docs/devel/lockcnt.rst

14 ``QLIST_FOREACH_SAFE`` protects against deletion of the current node (``ioh``)
16 actually delete the next node from the list.  The simplest way to
17 avoid this is to mark the node as deleted, and remove it from the
18 list in the above loop::
32 ``ioh->fd_write`` invokes the loop again, some kind of counting is needed::
49 One may think of using the RCU primitives, ``rcu_read_lock()`` and
50 ``rcu_read_unlock()``; effectively, the RCU nesting count would take
51 the place of the walking_handlers global variable.  Indeed,
59 - reference counting works even in the presence of code that keeps
65   the introduction of threads by many years.  RCU is generally used to
69 - reclaiming data can be done by a separate thread in the case of RCU;
81 to increment and decrement the counter, and to take and release the
82 mutex.  The counter notes how many visits to the data structures are
83 taking place (the visits could be from different threads, or there could
84 be multiple reentrant visits from the same thread).  The basic rules
85 governing the counter/mutex pair then are the following:
87 - Data protected by the QemuLockCnt must not be freed unless the
88   counter is zero and the mutex is taken.
90 - A new visit cannot be started while the counter is zero and the
93 Most of the time, the mutex protects all writes to the data structure,
96 Reads, instead, can be done without taking the mutex, as long as the
97 readers and writers use the same macros that are used for RCU, for
99 etc.  This is because the reads are done outside a lock and a set
101 can happen concurrently with the read.  The RCU API ensures that the
102 processor and the compiler see all required memory barriers.
104 This could be implemented simply by protecting the counter with the
126 Here, no frees can happen in the code represented by the ellipsis.
128 the code cannot be entered, because the thread will not be able
129 to increment the ``walking_handlers`` variable.  And of course
130 during the visit any other thread will see a nonzero value for
131 ``walking_handlers``, as in the single-threaded code.
134 the cleanup arbitrarily; in other words, for the ``walking_handlers``
136 more easily applicable if concurrent access to the structure is rare.
139 them for each modification of the counter.  ``QemuLockCnt`` ensures that
140 all modifications of the counter take the lock appropriately, and it
143 - it avoids taking the lock for many operations (for example
144   incrementing the counter while it is non-zero);
146 - on some platforms, one can implement ``QemuLockCnt`` to hold the lock
147   and the mutex in a single word, making the fast path no more expensive
150   the data structure is expected to be rare.
153 Using the same mutex for frees and writes can still incur some small
154 inefficiencies; for example, a visit can never start if the counter is
155 zero and the mutex is taken -- even if the mutex is taken by a write,
156 which in principle need not block a visit of the data structure.
157 However, these are usually not a problem if any of the following
168 bottom halves and file descriptor handlers.  Modifications to the list
171 concurrent with a visit to the list of bottom halves; 2) it only has
172 three instructions in the critical path, two assignments and a ``smp_wmb()``.
184 This section explains the typical usage patterns for ``QemuLockCnt`` functions.
197 Accessing the value can be done between ``qemu_lockcnt_inc`` and
208 Freeing the object can similarly use ``qemu_lockcnt_lock`` and
209 ``qemu_lockcnt_unlock``, but you also need to ensure that the count
211 takes the ``QemuLockCnt``'s lock, the count cannot become non-zero while
212 the object is being freed.  Freeing an object looks like this::
222 the decrement, the locking and the check on count as follows::
255 Again, the RCU primitives are used because new items can be added to the
256 list during the walk.  ``QLIST_FOREACH_RCU`` ensures that the processor and
257 the compiler see the appropriate memory barriers.
278 because there is no special task to do if the count goes from 1 to 0.