From b285374a9ad46cbc5edc8c071d85d6d895e9eb37 Mon Sep 17 00:00:00 2001 From: =?utf8?q?J=C3=A9r=C3=A9mie=20Galarneau?= Date: Fri, 10 Feb 2023 14:45:39 -0500 Subject: [PATCH] Docs: clarify grace period polling API MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Reword the existing grace period polling API documentation. The changes are: - Replace "should" by "must" to express obligations, - Attempt to clarify "which" grace period the API allows checking for. Change-Id: Ib3a93faeef7bcdb94ebae2d294d45925e12873a4 Signed-off-by: Jérémie Galarneau Signed-off-by: Mathieu Desnoyers --- doc/rcu-api.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/doc/rcu-api.md b/doc/rcu-api.md index 4163eef..804b212 100644 --- a/doc/rcu-api.md +++ b/doc/rcu-api.md @@ -64,20 +64,25 @@ actually waited is called an RCU grace period. struct urcu_gp_poll_state start_poll_synchronize_rcu(void); ``` -Start polling on grace period. The returned poll state should be -queried using `poll_state_synchronize_rcu` to check whether the -grace period has completed. +Provides a handle for checking if a new grace period has started +and completed since the handle was obtained. It returns a +`struct urcu_gp_poll_state` handle that can be used with +`poll_state_synchronize_rcu` to check, by polling, if the +associated grace period has completed. -`start_poll_synchronize_rcu` should be called from registered RCU -read-side threads. For the QSBR flavor, the caller should be online. +`start_poll_synchronize_rcu` must only be called from +registered RCU read-side threads. For the QSBR flavor, the +caller must be online. ```c bool poll_state_synchronize_rcu(struct urcu_gp_poll_state state); ``` -Poll the grace period state. Return true if quiescence was reached since -the grace period was started, return false otherwise. +Checks if the grace period associated with the +`struct urcu_gp_poll_state` handle has completed. If the grace +period has completed, the function returns true. Otherwise, +it returns false. ```c -- 2.34.1