Gh0st
/
linux
mirror of https://github.com/torvalds/linux.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

documentation: seqlock: fix the wrong documentation of read_seqbegin_or_lock/need_seqretry 

The comments and pseudo code in Documentation/locking/seqlock.rst are wrong:

	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() always returns with an even "seq" and 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>
Signed-off-by: Peter Zijlstra (Intel) <peterz@infradead.org>
This commit is contained in:
Oleg Nesterov 2025-09-28 18:20:29 +02:00 committed by Peter Zijlstra
parent 44472d1b83
commit 28a0ee3119
1 changed files with 5 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
Documentation/locking/seqlock.rst
View File

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