Commit ee7f4a87 authored by Paul E. McKenney's avatar Paul E. McKenney
Browse files

srcu: Document polling interfaces for Tree SRCU grace periods 

This commit adds requirements documentation for the
get_state_synchronize_srcu(), start_poll_synchronize_srcu(), and
poll_state_synchronize_srcu() functions.

Link: https://lore.kernel.org/rcu/20201112201547.GF3365678@moria.home.lan/


Reported-by: default avatarKent Overstreet <kent.overstreet@gmail.com>
Reviewed-by: default avatarNeeraj Upadhyay <neeraju@codeaurora.org>
Signed-off-by: default avatarPaul E. McKenney <paulmck@kernel.org>
parent 5358c9fa

Documentation/RCU/Design/Requirements/Requirements.rst

+18 −0
Original line number Diff line number Diff line
@@ -2600,6 +2600,24 @@ also includes ``DEFINE_SRCU()``, ``DEFINE_STATIC_SRCU()``, and 
``init_srcu_struct()`` APIs for defining and initializing

``srcu_struct`` structures.



More recently, the SRCU API has added polling interfaces:



#. start_poll_synchronize_srcu() returns a cookie identifying

   the completion of a future SRCU grace period and ensures

   that this grace period will be started.

#. poll_state_synchronize_srcu() returns ``true`` iff the

   specified cookie corresponds to an already-completed

   SRCU grace period.

#. get_state_synchronize_srcu() returns a cookie just like

   start_poll_synchronize_srcu() does, but differs in that

   it does nothing to ensure that any future SRCU grace period

   will be started.



These functions are used to avoid unnecessary SRCU grace periods in

certain types of buffer-cache algorithms having multi-stage age-out

mechanisms.  The idea is that by the time the block has aged completely

from the cache, an SRCU grace period will be very likely to have elapsed.



Tasks RCU

~~~~~~~~~