diff mbox series

[1/2] seqlock: fix the wrong read_seqbegin_or_lock/need_seqretry documentation

Message ID 20231024120808.GA15382@redhat.com
State New
Headers
Series [1/2] seqlock: fix the wrong read_seqbegin_or_lock/need_seqretry documentation |

Commit Message

Oleg Nesterov Oct. 24, 2023, 12:08 p.m. UTC 
  Half of the read_seqbegin_or_lock's users are buggy (I'll send the
fixes), and I guess this is because the documentation and the pseudo
code in Documentation/locking/seqlock.rst are wrong.

Pseudo code:

	int seq = 0;
	do {
		read_seqbegin_or_lock(&foo_seqlock, &seq);

		/* ... [[read-side critical section]] ... */

	} while (need_seqretry(&foo_seqlock, seq));

read_seqbegin_or_lock() returns with the even seq, need_seqretry()
doesn't change this counter. This means that seq is always even and
thus the locking pass is simply impossible.

IOW, "_or_lock" has no effect and this code doesn't differ from

	do {
		seq = read_seqbegin(&foo_seqlock);

		/* ... [[read-side critical section]] ... */

	} while (read_seqretry(&foo_seqlock, seq));

Signed-off-by: Oleg Nesterov <oleg@redhat.com>
---
 Documentation/locking/seqlock.rst | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

Comments

Oleg Nesterov Nov. 16, 2023, 2:45 p.m. UTC | #1 
Ping.

Please ignore 2/2 for now (it obviously wasn't for inclusion),
but the wrong documentation confuses the users.

fs/afs, rxrpc_find_service_conn_rcu, nfsd_copy_write_verifier
use read_seqbegin_or_lock/need_seqretry according to this doc
and they are wrong.

I am discussing the necessary changes in the code paths above,
but can't we fix the documentation?

On 10/24, Oleg Nesterov wrote:
>
> Half of the read_seqbegin_or_lock's users are buggy (I'll send the
> fixes), and I guess this is because the documentation and the pseudo
> code in Documentation/locking/seqlock.rst are wrong.
> 
> Pseudo code:
> 
> 	int seq = 0;
> 	do {
> 		read_seqbegin_or_lock(&foo_seqlock, &seq);
> 
> 		/* ... [[read-side critical section]] ... */
> 
> 	} while (need_seqretry(&foo_seqlock, seq));
> 
> read_seqbegin_or_lock() returns with the even seq, need_seqretry()
> doesn't change this counter. This means that seq is always even and
> thus the locking pass is simply impossible.
> 
> IOW, "_or_lock" has no effect and this code doesn't differ from
> 
> 	do {
> 		seq = read_seqbegin(&foo_seqlock);
> 
> 		/* ... [[read-side critical section]] ... */
> 
> 	} while (read_seqretry(&foo_seqlock, seq));
> 
> Signed-off-by: Oleg Nesterov <oleg@redhat.com>
> ---
>  Documentation/locking/seqlock.rst | 9 +++++----
>  1 file changed, 5 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/locking/seqlock.rst b/Documentation/locking/seqlock.rst
> index bfda1a5fecad..4bdf8d4ed2a2 100644
> --- a/Documentation/locking/seqlock.rst
> +++ b/Documentation/locking/seqlock.rst
> @@ -218,13 +218,14 @@ Read path, three categories:
>     according to a passed marker. This is used to avoid lockless readers
>     starvation (too much retry loops) in case of a sharp spike in write
>     activity. First, a lockless read is tried (even marker passed). If
> -   that trial fails (odd sequence counter is returned, which is used as
> -   the next iteration marker), the lockless read is transformed to a
> -   full locking read and no retry loop is necessary::
> +   that trial fails (sequence counter doesn't match), make the marker
> +   odd for the next iteration, the lockless read is transformed to a
> +   full locking read and no retry loop is necessary, for example::
>  
>  	/* marker; even initialization */
> -	int seq = 0;
> +	int seq = 1;
>  	do {
> +		seq++; /* 2 on the 1st/lockless path, otherwise odd */
>  		read_seqbegin_or_lock(&foo_seqlock, &seq);
>  
>  		/* ... [[read-side critical section]] ... */
> -- 
> 2.25.1.362.g51ebf55
>
diff mbox series

Patch

diff --git a/Documentation/locking/seqlock.rst b/Documentation/locking/seqlock.rst
index bfda1a5fecad..4bdf8d4ed2a2 100644
--- a/Documentation/locking/seqlock.rst
+++ b/Documentation/locking/seqlock.rst
@@ -218,13 +218,14 @@  Read path, three categories:
    according to a passed marker. This is used to avoid lockless readers
    starvation (too much retry loops) in case of a sharp spike in write
    activity. First, a lockless read is tried (even marker passed). If
-   that trial fails (odd sequence counter is returned, which is used as
-   the next iteration marker), the lockless read is transformed to a
-   full locking read and no retry loop is necessary::
+   that trial fails (sequence counter doesn't match), make the marker
+   odd for the next iteration, the lockless read is transformed to a
+   full locking read and no retry loop is necessary, for example::
 
 	/* marker; even initialization */
-	int seq = 0;
+	int seq = 1;
 	do {
+		seq++; /* 2 on the 1st/lockless path, otherwise odd */
 		read_seqbegin_or_lock(&foo_seqlock, &seq);
 
 		/* ... [[read-side critical section]] ... */