From: Jérémie Galarneau Date: Fri, 10 Feb 2023 19:45:39 +0000 (-0500) Subject: Docs: clarify grace period polling API X-Git-Tag: v0.14.0~5 X-Git-Url: https://git.lttng.org./?a=commitdiff_plain;h=b285374a9ad46cbc5edc8c071d85d6d895e9eb37;p=urcu.git Docs: clarify grace period polling API 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 --- 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