[PATCH] rcu_sync: Fix comment to properly reflect rcu_sync_exit() behavior

[PATCH] rcu_sync: Fix comment to properly reflect rcu_sync_exit() behavior

[David Vernet]

rcu_sync_enter() is an rcu_sync API used by updaters which forces RCU
readers (e.g. percpu-rwsem) to take a slow-path during an update. It does
this by setting the gp_state of the rcu_sync object to GP_ENTER (i.e. > 0).
In this state, readers will take a "slow path", such as having percpu-rwsem
readers wait on a semaphore rather than just incrementing a reader count.
When the updater has completed their work, they must invoke rcu_sync_exit()
to signal to readers that they may again take their fastpaths.

rcu_sync_enter() currently has a comment that stipulates that a later call
to rcu_sync_exit() (by an updater) will re-enable reader "slowpaths". This
patch corrects the comment to properly reflect that rcu_sync_exit()
re-enables reader fastpaths.

Signed-off-by: David Vernet <void@manifault.com>
---
 kernel/rcu/sync.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/kernel/rcu/sync.c b/kernel/rcu/sync.c
index 33d896d85902..5cefc702158f 100644
--- a/kernel/rcu/sync.c
+++ b/kernel/rcu/sync.c
@@ -111,7 +111,7 @@ static void rcu_sync_func(struct rcu_head *rhp)
  * a slowpath during the update.  After this function returns, all
  * subsequent calls to rcu_sync_is_idle() will return false, which
  * tells readers to stay off their fastpaths.  A later call to
- * rcu_sync_exit() re-enables reader slowpaths.
+ * rcu_sync_exit() re-enables reader fastpaths.
  *
  * When called in isolation, rcu_sync_enter() must wait for a grace
  * period, however, closely spaced calls to rcu_sync_enter() can
-- 
2.30.2

Re: [PATCH] rcu_sync: Fix comment to properly reflect rcu_sync_exit() behavior

[Paul E. McKenney]

On Tue, Mar 29, 2022 at 03:26:13PM -0700, David Vernet wrote:
> rcu_sync_enter() is an rcu_sync API used by updaters which forces RCU
> readers (e.g. percpu-rwsem) to take a slow-path during an update. It does
> this by setting the gp_state of the rcu_sync object to GP_ENTER (i.e. > 0).
> In this state, readers will take a "slow path", such as having percpu-rwsem
> readers wait on a semaphore rather than just incrementing a reader count.
> When the updater has completed their work, they must invoke rcu_sync_exit()
> to signal to readers that they may again take their fastpaths.
> 
> rcu_sync_enter() currently has a comment that stipulates that a later call
> to rcu_sync_exit() (by an updater) will re-enable reader "slowpaths". This
> patch corrects the comment to properly reflect that rcu_sync_exit()
> re-enables reader fastpaths.
> 
> Signed-off-by: David Vernet <void@manifault.com>

Good eyes, thank you!

As usual, I could not resist the urge to wordsmith.  Please take a look
at the following to see if I messed something up.

							Thanx, Paul

------------------------------------------------------------------------

commit b89e06a95c05009bcf31949814c42bc420f414a6
Author: David Vernet <void@manifault.com>
Date:   Tue Mar 29 15:26:13 2022 -0700

    rcu_sync: Fix comment to properly reflect rcu_sync_exit() behavior
    
    The rcu_sync_enter() function is used by updaters to force RCU readers
    (e.g. percpu-rwsem) to use their slow paths during an update.  This is
    accomplished by setting the ->gp_state of the rcu_sync structure to
    GP_ENTER.  In the case of percpu-rwsem, the readers' slow path waits on
    a semaphore instead of just incrementing a reader count.  Each updater
    invokes the rcu_sync_exit() function to signal to readers that they
    may again take their fastpaths.  The rcu_sync_exit() function sets the
    ->gp_state of the rcu_sync structure to GP_EXIT, and if all goes well,
    after a grace period the ->gp_state reverts back to GP_IDLE.
    
    Unfortunately, the rcu_sync_enter() function currently has a comment
    incorrectly stating that rcu_sync_exit() (by an updater) will re-enable
    reader "slowpaths".  This patch changes the comment to state that this
    function re-enables reader fastpaths.
    
    Signed-off-by: David Vernet <void@manifault.com>
    Signed-off-by: Paul E. McKenney <paulmck@kernel.org>

diff --git a/kernel/rcu/sync.c b/kernel/rcu/sync.c
index 33d896d85902..5cefc702158f 100644
--- a/kernel/rcu/sync.c
+++ b/kernel/rcu/sync.c
@@ -111,7 +111,7 @@ static void rcu_sync_func(struct rcu_head *rhp)
  * a slowpath during the update.  After this function returns, all
  * subsequent calls to rcu_sync_is_idle() will return false, which
  * tells readers to stay off their fastpaths.  A later call to
- * rcu_sync_exit() re-enables reader slowpaths.
+ * rcu_sync_exit() re-enables reader fastpaths.
  *
  * When called in isolation, rcu_sync_enter() must wait for a grace
  * period, however, closely spaced calls to rcu_sync_enter() can

Re: [PATCH] rcu_sync: Fix comment to properly reflect rcu_sync_exit() behavior

[David Vernet]

On Tue, Mar 29, 2022 at 04:22:56PM -0700, Paul E. McKenney wrote:
> As usual, I could not resist the urge to wordsmith.  Please take a look
> at the following to see if I messed something up.
> 
> 							Thanx, Paul
> 
> ------------------------------------------------------------------------
> 
> commit b89e06a95c05009bcf31949814c42bc420f414a6
> Author: David Vernet <void@manifault.com>
> Date:   Tue Mar 29 15:26:13 2022 -0700
> 
>     rcu_sync: Fix comment to properly reflect rcu_sync_exit() behavior
>     
>     The rcu_sync_enter() function is used by updaters to force RCU readers
>     (e.g. percpu-rwsem) to use their slow paths during an update.  This is
>     accomplished by setting the ->gp_state of the rcu_sync structure to
>     GP_ENTER.  In the case of percpu-rwsem, the readers' slow path waits on
>     a semaphore instead of just incrementing a reader count.  Each updater
>     invokes the rcu_sync_exit() function to signal to readers that they
>     may again take their fastpaths.  The rcu_sync_exit() function sets the
>     ->gp_state of the rcu_sync structure to GP_EXIT, and if all goes well,
>     after a grace period the ->gp_state reverts back to GP_IDLE.
>     
>     Unfortunately, the rcu_sync_enter() function currently has a comment
>     incorrectly stating that rcu_sync_exit() (by an updater) will re-enable
>     reader "slowpaths".  This patch changes the comment to state that this
>     function re-enables reader fastpaths.
>     
>     Signed-off-by: David Vernet <void@manifault.com>
>     Signed-off-by: Paul E. McKenney <paulmck@kernel.org>

The word smithing looks like a good improvement to me!

Thanks,
David