2019-08-31 13:42:57

by Federico Vaga

[permalink] [raw]
Subject: [PATCH] doc:lock: remove reference to clever use of read-write lock

Remove the clever example about read-write lock because these type of
lock is not reccomended anymore (according to the very same document).
So there is no reason to teach cleaver things that people should not do.

(and by the way there was a little typo)

Signed-off-by: Federico Vaga <[email protected]>
---
Documentation/locking/spinlocks.rst | 14 +-------------
1 file changed, 1 insertion(+), 13 deletions(-)

diff --git a/Documentation/locking/spinlocks.rst b/Documentation/locking/spinlocks.rst
index e93ec6645238..8053fd4c3544 100644
--- a/Documentation/locking/spinlocks.rst
+++ b/Documentation/locking/spinlocks.rst
@@ -106,7 +106,7 @@ and on other architectures it can be worse).

If you have a case where you have to protect a data structure across
several CPU's and you want to use spinlocks you can potentially use
-cheaper versions of the spinlocks. IFF you know that the spinlocks are
+cheaper versions of the spinlocks. If you know that the spinlocks are
never used in interrupt handlers, you can use the non-irq versions::

spin_lock(&lock);
@@ -139,18 +139,6 @@ on other CPU's, because an interrupt on another CPU doesn't interrupt the
CPU that holds the lock, so the lock-holder can continue and eventually
releases the lock).

-Note that you can be clever with read-write locks and interrupts. For
-example, if you know that the interrupt only ever gets a read-lock, then
-you can use a non-irq version of read locks everywhere - because they
-don't block on each other (and thus there is no dead-lock wrt interrupts.
-But when you do the write-lock, you have to use the irq-safe version.
-
-For an example of being clever with rw-locks, see the "waitqueue_lock"
-handling in kernel/sched/core.c - nothing ever _changes_ a wait-queue from
-within an interrupt, they only read the queue in order to know whom to
-wake up. So read-locks are safe (which is good: they are very common
-indeed), while write-locks need to protect themselves against interrupts.
-
Linus

----
--
2.21.0


2019-08-31 14:44:55

by Jonathan Corbet

[permalink] [raw]
Subject: Re: [PATCH] doc:lock: remove reference to clever use of read-write lock

On Sat, 31 Aug 2019 15:41:16 +0200
Federico Vaga <[email protected]> wrote:

> several CPU's and you want to use spinlocks you can potentially use
> -cheaper versions of the spinlocks. IFF you know that the spinlocks are
> +cheaper versions of the spinlocks. If you know that the spinlocks are
> never used in interrupt handlers, you can use the non-irq versions::

I suspect that was not actually a typo; "iff" is a way for the
mathematically inclined to say "if and only if".

jon

2019-09-02 07:06:00

by Federico Vaga

[permalink] [raw]
Subject: Re: [PATCH] doc:lock: remove reference to clever use of read-write lock

On Saturday, August 31, 2019 4:43:44 PM CEST Jonathan Corbet wrote:
> On Sat, 31 Aug 2019 15:41:16 +0200
>
> Federico Vaga <[email protected]> wrote:
> > several CPU's and you want to use spinlocks you can potentially use
> >
> > -cheaper versions of the spinlocks. IFF you know that the spinlocks are
> > +cheaper versions of the spinlocks. If you know that the spinlocks are
> >
> > never used in interrupt handlers, you can use the non-irq versions::
> I suspect that was not actually a typo; "iff" is a way for the
> mathematically inclined to say "if and only if".
>
> jon

I learned something new today :)

I am not used to the mathematical English jargon. It make sense, but then I
would replace it with "If and only if": for clarity.


--
Federico Vaga



2019-09-02 18:12:43

by Ingo Molnar

[permalink] [raw]
Subject: Re: [PATCH] doc:lock: remove reference to clever use of read-write lock


* Federico Vaga <[email protected]> wrote:

> On Saturday, August 31, 2019 4:43:44 PM CEST Jonathan Corbet wrote:
> > On Sat, 31 Aug 2019 15:41:16 +0200
> >
> > Federico Vaga <[email protected]> wrote:
> > > several CPU's and you want to use spinlocks you can potentially use
> > >
> > > -cheaper versions of the spinlocks. IFF you know that the spinlocks are
> > > +cheaper versions of the spinlocks. If you know that the spinlocks are
> > >
> > > never used in interrupt handlers, you can use the non-irq versions::
> > I suspect that was not actually a typo; "iff" is a way for the
> > mathematically inclined to say "if and only if".
> >
> > jon
>
> I learned something new today :)
>
> I am not used to the mathematical English jargon. It make sense, but then I
> would replace it with "If and only if": for clarity.

While it's used in a number of places and it's pretty common wording
overall in the literature, I agree that we should probably change this in
locking API user facing documentation.

If you change it, please do it in both places it's used.

Thanks,

Ingo

2019-09-02 19:20:33

by Federico Vaga

[permalink] [raw]
Subject: Re: [PATCH] doc:lock: remove reference to clever use of read-write lock

On Monday, September 2, 2019 8:10:10 PM CEST Ingo Molnar wrote:
> * Federico Vaga <[email protected]> wrote:
> > On Saturday, August 31, 2019 4:43:44 PM CEST Jonathan Corbet wrote:
> > > On Sat, 31 Aug 2019 15:41:16 +0200
> > >
> > > Federico Vaga <[email protected]> wrote:
> > > > several CPU's and you want to use spinlocks you can potentially use
> > > >
> > > > -cheaper versions of the spinlocks. IFF you know that the spinlocks
> > > > are
> > > > +cheaper versions of the spinlocks. If you know that the spinlocks are
> > > >
> > > > never used in interrupt handlers, you can use the non-irq versions::
> > > I suspect that was not actually a typo; "iff" is a way for the
> > > mathematically inclined to say "if and only if".
> > >
> > > jon
> >
> > I learned something new today :)
> >
> > I am not used to the mathematical English jargon. It make sense, but then
> > I
> > would replace it with "If and only if": for clarity.
>
> While it's used in a number of places and it's pretty common wording
> overall in the literature, I agree that we should probably change this in
> locking API user facing documentation.

I would say not only in locking/. The argument is valid for the entire
Documentation/. I wait for Jon's opinion before proceeding.

> If you change it, please do it in both places it's used.
>
> Thanks,
>
> Ingo




2019-09-02 20:22:35

by Jonathan Corbet

[permalink] [raw]
Subject: Re: [PATCH] doc:lock: remove reference to clever use of read-write lock

On Mon, 02 Sep 2019 21:19:24 +0200
Federico Vaga <[email protected]> wrote:

> > > I am not used to the mathematical English jargon. It make sense, but then
> > > I
> > > would replace it with "If and only if": for clarity.
> >
> > While it's used in a number of places and it's pretty common wording
> > overall in the literature, I agree that we should probably change this in
> > locking API user facing documentation.
>
> I would say not only in locking/. The argument is valid for the entire
> Documentation/. I wait for Jon's opinion before proceeding.

I don't really have a problem with "iff"; it doesn't seem like *that*
obscure a term to me. But if you want spell it out, I guess I don't have
a problem with that. We can change it - iff you send a patch to do it :)

Thanks,

jon

2019-09-02 21:08:27

by Federico Vaga

[permalink] [raw]
Subject: Re: [PATCH] doc:lock: remove reference to clever use of read-write lock

On Monday, September 2, 2019 10:21:33 PM CEST Jonathan Corbet wrote:
> On Mon, 02 Sep 2019 21:19:24 +0200
>
> Federico Vaga <[email protected]> wrote:
> > > > I am not used to the mathematical English jargon. It make sense, but
> > > > then
> > > > I
> > > > would replace it with "If and only if": for clarity.
> > >
> > > While it's used in a number of places and it's pretty common wording
> > > overall in the literature, I agree that we should probably change this
> > > in
> > > locking API user facing documentation.
> >
> > I would say not only in locking/. The argument is valid for the entire
> > Documentation/. I wait for Jon's opinion before proceeding.
>
> I don't really have a problem with "iff"; it doesn't seem like *that*
> obscure a term to me. But if you want spell it out, I guess I don't have
> a problem with that. We can change it - iff you send a patch to do it :)

I do not mind too, once I got the meaning of IFF to *me* is clear and
translatable to SSE (i will not).

My opinion is that abbreviations should not be used in general. But it is a
weak opinion. I can do, and send, a patch

>
> Thanks,
>
> jon




2019-09-03 02:39:48

by Matthew Wilcox

[permalink] [raw]
Subject: Re: [PATCH] doc:lock: remove reference to clever use of read-write lock

On Mon, Sep 02, 2019 at 02:21:33PM -0600, Jonathan Corbet wrote:
> On Mon, 02 Sep 2019 21:19:24 +0200
> Federico Vaga <[email protected]> wrote:
>
> > > > I am not used to the mathematical English jargon. It make sense, but then
> > > > I
> > > > would replace it with "If and only if": for clarity.
> > >
> > > While it's used in a number of places and it's pretty common wording
> > > overall in the literature, I agree that we should probably change this in
> > > locking API user facing documentation.
> >
> > I would say not only in locking/. The argument is valid for the entire
> > Documentation/. I wait for Jon's opinion before proceeding.
>
> I don't really have a problem with "iff"; it doesn't seem like *that*
> obscure a term to me. But if you want spell it out, I guess I don't have
> a problem with that. We can change it - iff you send a patch to do it :)

$ git grep -iwc iff Documentation
Documentation/admin-guide/cgroup-v1/blkio-controller.rst:1
Documentation/admin-guide/cgroup-v1/cgroups.rst:1
Documentation/admin-guide/cgroup-v1/freezer-subsystem.rst:2
Documentation/admin-guide/cgroup-v2.rst:1
Documentation/devicetree/bindings/media/st-rc.txt:2
Documentation/devicetree/bindings/net/ibm,emac.txt:5
Documentation/devicetree/bindings/pinctrl/pinctrl-st.txt:1
Documentation/driver-api/libata.rst:1
Documentation/features/scripts/features-refresh.sh:1
Documentation/filesystems/directory-locking:1
Documentation/i2c/i2c-topology:3
Documentation/ioctl/hdio.rst:1
Documentation/locking/spinlocks.rst:1
Documentation/locking/ww-mutex-design.rst:1
Documentation/scsi/scsi_eh.txt:2
Documentation/spi/spidev:2
Documentation/trace/ring-buffer-design.txt:1
Documentation/virt/kvm/api.txt:1
Documentation/virt/kvm/halt-polling.txt:1

(29 total)

Of course that doesn't count any in kernel-doc.

2019-09-05 09:45:09

by Federico Vaga

[permalink] [raw]
Subject: Re: [PATCH] doc:lock: remove reference to clever use of read-write lock

On Saturday, August 31, 2019 4:43:44 PM CEST Jonathan Corbet wrote:
> On Sat, 31 Aug 2019 15:41:16 +0200
>
> Federico Vaga <[email protected]> wrote:
> > several CPU's and you want to use spinlocks you can potentially use
> >
> > -cheaper versions of the spinlocks. IFF you know that the spinlocks are
> > +cheaper versions of the spinlocks. If you know that the spinlocks are
> >
> > never used in interrupt handlers, you can use the non-irq versions::
> I suspect that was not actually a typo; "iff" is a way for the
> mathematically inclined to say "if and only if".

Unfortunately this thread focused on this little thing ^_^'

What about the patch itself? Should I send a new one without this fix or you
will apply it as it is?