diff options
| author | Joel Fernandes (Google) <joel@joelfernandes.org> | 2018-09-25 11:26:00 -0700 |
|---|---|---|
| committer | Paul E. McKenney <paulmck@linux.ibm.com> | 2018-11-12 08:56:25 -0800 |
| commit | 82eccec851478e55bfd398d7e9d03300026fc4a9 (patch) | |
| tree | e5bdca0c9dcb6dba286bafb8e1f6dff095d08a24 /Documentation/RCU | |
| parent | b54d9db26031d6dc96222164092eacbaa0329255 (diff) | |
doc: rcu: Better clarify the rcu_segcblist ->len field
An important note under the rcu_segcblist description could use a more
detailed description. Especially explanation of the scenario where the
->head field may be temporarily NULL making it not wise to rely on it
to determine if callbacks are associated with the rcu_segcblist.
Signed-off-by: Joel Fernandes (Google) <joel@joelfernandes.org>
Cc: <kernel-team@android.com>
Signed-off-by: Paul E. McKenney <paulmck@linux.ibm.com>
Diffstat (limited to 'Documentation/RCU')
| -rw-r--r-- | Documentation/RCU/Design/Data-Structures/Data-Structures.html | 23 |
1 files changed, 15 insertions, 8 deletions
diff --git a/Documentation/RCU/Design/Data-Structures/Data-Structures.html b/Documentation/RCU/Design/Data-Structures/Data-Structures.html index 28b241074c86..3ed5f0182bc4 100644 --- a/Documentation/RCU/Design/Data-Structures/Data-Structures.html +++ b/Documentation/RCU/Design/Data-Structures/Data-Structures.html @@ -928,17 +928,24 @@ this <tt>rcu_segcblist</tt> structure, <i>not</i> the <tt>->head</tt> pointer. The reason for this is that all the ready-to-invoke callbacks (that is, those in the <tt>RCU_DONE_TAIL</tt> segment) are extracted -all at once at callback-invocation time. +all at once at callback-invocation time (<tt>rcu_do_batch</tt>), due +to which <tt>->head</tt> may be set to NULL if there are no not-done +callbacks remaining in the <tt>rcu_segcblist</tt>. If callback invocation must be postponed, for example, because a high-priority process just woke up on this CPU, then the remaining -callbacks are placed back on the <tt>RCU_DONE_TAIL</tt> segment. -Either way, the <tt>->len</tt> and <tt>->len_lazy</tt> counts -are adjusted after the corresponding callbacks have been invoked, and so -again it is the <tt>->len</tt> count that accurately reflects whether -or not there are callbacks associated with this <tt>rcu_segcblist</tt> -structure. +callbacks are placed back on the <tt>RCU_DONE_TAIL</tt> segment and +<tt>->head</tt> once again points to the start of the segment. +In short, the head field can briefly be <tt>NULL</tt> even though the +CPU has callbacks present the entire time. +Therefore, it is not appropriate to test the <tt>->head</tt> pointer +for <tt>NULL</tt>. + +<p>In contrast, the <tt>->len</tt> and <tt>->len_lazy</tt> counts +are adjusted only after the corresponding callbacks have been invoked. +This means that the <tt>->len</tt> count is zero only if +the <tt>rcu_segcblist</tt> structure really is devoid of callbacks. Of course, off-CPU sampling of the <tt>->len</tt> count requires -the use of appropriate synchronization, for example, memory barriers. +careful use of appropriate synchronization, for example, memory barriers. This synchronization can be a bit subtle, particularly in the case of <tt>rcu_barrier()</tt>. |