The following commit has been merged into the core/rcu branch of tip: Commit-ID: ee7f4a87a18cd3bb141b38e2ef0c3e53253cdf63 Gitweb: https://git.kernel.org/tip/ee7f4a87a18cd3bb141b38e2ef0c3e53253cdf63 Author: Paul E. McKenney <paulmck@xxxxxxxxxx> AuthorDate: Wed, 18 Nov 2020 16:01:32 -08:00 Committer: Paul E. McKenney <paulmck@xxxxxxxxxx> CommitterDate: Mon, 04 Jan 2021 13:53:39 -08:00 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@xxxxxxxxxxxxxx/ Reported-by: Kent Overstreet <kent.overstreet@xxxxxxxxx> Reviewed-by: Neeraj Upadhyay <neeraju@xxxxxxxxxxxxxx> Signed-off-by: Paul E. McKenney <paulmck@xxxxxxxxxx> --- Documentation/RCU/Design/Requirements/Requirements.rst | 18 +++++++++- 1 file changed, 18 insertions(+) diff --git a/Documentation/RCU/Design/Requirements/Requirements.rst b/Documentation/RCU/Design/Requirements/Requirements.rst index e8c84fc..93a189a 100644 --- a/Documentation/RCU/Design/Requirements/Requirements.rst +++ b/Documentation/RCU/Design/Requirements/Requirements.rst @@ -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 ~~~~~~~~~
|