On Fri, 22 May 2020 20:01:45 +0200 Peter Zijlstra <peterz@xxxxxxxxxxxxx> 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
