Received: by 2002:a25:1104:0:0:0:0:0 with SMTP id 4csp634794ybr; Fri, 22 May 2020 15:26:15 -0700 (PDT) X-Google-Smtp-Source: ABdhPJyGgP1n7Fgbp4diOmOaAfpKO0aO7FfEjZOTGG8eMH7ERj3NMBSOueVOouXNTw0+5FxBeIFR X-Received: by 2002:a17:906:3652:: with SMTP id r18mr9841371ejb.526.1590186375495; Fri, 22 May 2020 15:26:15 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1590186375; cv=none; d=google.com; s=arc-20160816; b=G9tre6lGzPGtLUWjGXCTJV5UfwY/Zzw0b7qUB0LmdIRRae9Hl1+uwfxIu/pqKwlxYY jHJ8Lbq3XMx+2sUGe2YxfbP9p4uS8K3TiC5blrQgu2Xf7qd2MFSLxbKqjhEJeC6wnAR2 DK4+xgvR+sD0PYlZxZBRCgqMoKm6AL/Xy2oxqzNtKM1yV9jEoAbwGi4TfZp0mrQzLi80 a08p6Sq0E3p86LMvBXxOXYGbaHbSKO8+B/5eG+gIlJrGbxBVH4wFQjb7B0e2D/jR/kBe KhEEiCvZowZAXfMBsjgkijjaY5F0qYebXfbN4SM5Ks05OiXGmgumcPYn8Z0PknxSWvMm YG1Q== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:content-transfer-encoding:mime-version :references:in-reply-to:message-id:subject:cc:to:from:date; bh=HR9Y/Qs1Q/4tvS9rFrcVCwemxyW2zR8wb6QzduaZ9fY=; b=tNmj+SyvtFPAnBWreOJHtTUPP/ott4xutu++Nq89UiPPHY+cOnDM11uSvGUHQFWQEQ LWskwRXwZ4JW3Lj4FM19nzz3opcdpI1IBMVsfvgKk0djWAqKfbH1N6mt5t/7W8NFDUAP 7gXep+ADtxU3+qH46YIppnAs3Kj5qxK9CMUPC9hdWHDRpqaMDFq90XowWnVKDCwO7W2O m7WW0c8cf9PDLaAhWMIEXGWSDfAtBFQ1mEknR+ElJBiQBC/PrIlFmM+CkyC8fBFqaUe2 Lx8qlwjg1Zld9Pv69sHZlgH92k6jkwfpQ2aw95NKsy4vcpQlgCbsZ0G0Eh/wJG9Evh9z Kr4Q== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [23.128.96.18]) by mx.google.com with ESMTP id qq4si5767237ejb.660.2020.05.22.15.25.53; Fri, 22 May 2020 15:26:15 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18; Authentication-Results: mx.google.com; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1731197AbgEVWYO (ORCPT + 99 others); Fri, 22 May 2020 18:24:14 -0400 Received: from mail.kernel.org ([198.145.29.99]:48852 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1731093AbgEVWYN (ORCPT ); Fri, 22 May 2020 18:24:13 -0400 Received: from oasis.local.home (cpe-66-24-58-225.stny.res.rr.com [66.24.58.225]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 331E32085B; Fri, 22 May 2020 22:24:12 +0000 (UTC) Date: Fri, 22 May 2020 18:24:09 -0400 From: Steven Rostedt To: Peter Zijlstra Cc: "Ahmed S. Darwish" , Ingo Molnar , Will Deacon , Thomas Gleixner , "Paul E. McKenney" , "Sebastian A. Siewior" , LKML , Jonathan Corbet , linux-doc@vger.kernel.org Subject: Re: [PATCH v1 09/25] Documentation: locking: Describe seqlock design and usage Message-ID: <20200522182409.4016d83c@oasis.local.home> In-Reply-To: <20200522180145.GR325280@hirez.programming.kicks-ass.net> References: <20200519214547.352050-1-a.darwish@linutronix.de> <20200519214547.352050-10-a.darwish@linutronix.de> <20200522180145.GR325280@hirez.programming.kicks-ass.net> X-Mailer: Claws Mail 3.17.3 (GTK+ 2.24.32; x86_64-pc-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Fri, 22 May 2020 20:01:45 +0200 Peter Zijlstra 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