From: Steven Rostedt <rostedt@goodmis.org>
To: Peter Zijlstra <peterz@infradead.org>
Cc: "Ahmed S. Darwish" <a.darwish@linutronix.de>,
Ingo Molnar <mingo@redhat.com>, Will Deacon <will@kernel.org>,
Thomas Gleixner <tglx@linutronix.de>,
"Paul E. McKenney" <paulmck@kernel.org>,
"Sebastian A. Siewior" <bigeasy@linutronix.de>,
LKML <linux-kernel@vger.kernel.org>,
Jonathan Corbet <corbet@lwn.net>,
linux-doc@vger.kernel.org
Subject: Re: [PATCH v1 09/25] Documentation: locking: Describe seqlock design and usage
Date: Fri, 22 May 2020 18:24:09 -0400 [thread overview]
Message-ID: <20200522182409.4016d83c@oasis.local.home> (raw)
In-Reply-To: <20200522180145.GR325280@hirez.programming.kicks-ass.net>
On Fri, 22 May 2020 20:01:45 +0200
Peter Zijlstra <peterz@infradead.org> wrote:
> On Tue, May 19, 2020 at 11:45:31PM +0200, Ahmed S. Darwish wrote:
> > diff --git a/include/linux/seqlock.h b/include/linux/seqlock.h
> > index d35be7709403..2a4af746b1da 100644
> > --- a/include/linux/seqlock.h
> > +++ b/include/linux/seqlock.h
> > @@ -1,36 +1,15 @@
> > /* SPDX-License-Identifier: GPL-2.0 */
> > #ifndef __LINUX_SEQLOCK_H
> > #define __LINUX_SEQLOCK_H
> > +
> > /*
> > - * Reader/writer consistent mechanism without starving writers. This type of
> > - * lock for data where the reader wants a consistent set of information
> > - * and is willing to retry if the information changes. There are two types
> > - * of readers:
> > - * 1. Sequence readers which never block a writer but they may have to retry
> > - * if a writer is in progress by detecting change in sequence number.
> > - * Writers do not wait for a sequence reader.
> > - * 2. Locking readers which will wait if a writer or another locking reader
> > - * is in progress. A locking reader in progress will also block a writer
> > - * from going forward. Unlike the regular rwlock, the read lock here is
> > - * exclusive so that only one locking reader can get it.
> > + * seqcount_t / seqlock_t - a reader-writer consistency mechanism with
> > + * lockless readers (read-only retry loops), and no writer starvation.
> > *
> > - * This is not as cache friendly as brlock. Also, this may not work well
> > - * for data that contains pointers, because any writer could
> > - * invalidate a pointer that a reader was following.
> > + * See Documentation/locking/seqlock.rst for full description.
>
> So I really really hate that... I _much_ prefer code comments to crappy
> documents.
Agreed. Comments are much less likely to bitrot than documents. The
farther away the documentation is from the code, the quicker it becomes
stale.
It's fine to add "See Documentation/..." but please don't *ever* remove
comments that's next to the actual code.
-- Steve
next prev parent reply other threads:[~2020-05-22 22:24 UTC|newest]
Thread overview: 42+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-05-19 21:45 [PATCH v1 00/25] seqlock: Extend seqcount API with associated locks Ahmed S. Darwish
2020-05-19 21:45 ` [PATCH v1 09/25] Documentation: locking: Describe seqlock design and usage Ahmed S. Darwish
2020-05-22 18:01 ` Peter Zijlstra
2020-05-22 22:24 ` Steven Rostedt [this message]
2020-05-25 10:50 ` Ahmed S. Darwish
2020-05-25 11:02 ` Ahmed S. Darwish
2020-05-19 21:45 ` [PATCH v1 10/25] seqlock: Add RST directives to kernel-doc code samples and notes Ahmed S. Darwish
2020-05-22 18:02 ` Peter Zijlstra
2020-05-22 18:03 ` Peter Zijlstra
2020-05-22 18:26 ` Thomas Gleixner
2020-05-22 18:32 ` Peter Zijlstra
2020-05-25 9:36 ` Ahmed S. Darwish
2020-05-25 13:44 ` Peter Zijlstra
2020-05-25 14:07 ` Peter Zijlstra
2020-05-19 21:45 ` [PATCH v1 11/25] seqlock: Add missing kernel-doc annotations Ahmed S. Darwish
2020-05-19 21:45 ` [PATCH v1 12/25] seqlock: Extend seqcount API with associated locks Ahmed S. Darwish
2020-06-08 0:57 ` [PATCH v2 00/18] " Ahmed S. Darwish
2020-06-08 0:57 ` [PATCH v2 01/18] Documentation: locking: Describe seqlock design and usage Ahmed S. Darwish
2020-06-08 0:57 ` [PATCH v2 02/18] seqlock: Properly format kernel-doc code samples Ahmed S. Darwish
2020-06-08 0:57 ` [PATCH v2 03/18] seqlock: Add missing kernel-doc annotations Ahmed S. Darwish
2020-06-30 5:44 ` [PATCH v3 00/20] seqlock: Extend seqcount API with associated locks Ahmed S. Darwish
2020-06-30 5:44 ` [PATCH v3 01/20] Documentation: locking: Describe seqlock design and usage Ahmed S. Darwish
2020-07-06 21:04 ` Peter Zijlstra
2020-07-06 21:12 ` Jonathan Corbet
2020-07-06 21:16 ` Peter Zijlstra
2020-07-07 10:12 ` Ahmed S. Darwish
2020-07-07 12:47 ` Peter Zijlstra
2020-06-30 5:44 ` [PATCH v3 02/20] seqlock: Properly format kernel-doc code samples Ahmed S. Darwish
2020-06-30 5:44 ` [PATCH v3 03/20] seqlock: Add missing kernel-doc annotations Ahmed S. Darwish
2020-07-20 15:55 ` [PATCH v4 00/24] seqlock: Extend seqcount API with associated locks Ahmed S. Darwish
2020-07-20 15:55 ` [PATCH v4 01/24] Documentation: locking: Describe seqlock design and usage Ahmed S. Darwish
2020-07-21 1:35 ` Steven Rostedt
2020-07-21 1:37 ` Steven Rostedt
2020-07-21 5:34 ` Ahmed S. Darwish
2020-07-21 1:44 ` Steven Rostedt
2020-07-21 1:51 ` Steven Rostedt
2020-07-21 7:15 ` Ahmed S. Darwish
2020-07-20 15:55 ` [PATCH v4 02/24] seqlock: Properly format kernel-doc code samples Ahmed S. Darwish
2020-07-20 15:55 ` [PATCH v4 03/24] seqlock: seqcount_t latch: End read sections with read_seqcount_retry() Ahmed S. Darwish
2020-07-20 15:55 ` [PATCH v4 05/24] seqlock: Add kernel-doc for seqcount_t and seqlock_t APIs Ahmed S. Darwish
2020-07-20 16:49 ` [PATCH v4 00/24] seqlock: Extend seqcount API with associated locks Eric Biggers
2020-07-20 17:33 ` Ahmed S. Darwish
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200522182409.4016d83c@oasis.local.home \
--to=rostedt@goodmis.org \
--cc=a.darwish@linutronix.de \
--cc=bigeasy@linutronix.de \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=mingo@redhat.com \
--cc=paulmck@kernel.org \
--cc=peterz@infradead.org \
--cc=tglx@linutronix.de \
--cc=will@kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).