[PATCH] manual: Document compiler and memory barriers

[PATCH] manual: Document compiler and memory barriers

[Florian Weimer]

-----
 manual/threads.texi | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)

diff --git a/manual/threads.texi b/manual/threads.texi
index 0858ef8f92..23e22dcca9 100644
--- a/manual/threads.texi
+++ b/manual/threads.texi
@@ -11,6 +11,7 @@ POSIX threads.
 @menu
 * ISO C Threads::	Threads based on the ISO C specification.
 * POSIX Threads::	Threads based on the POSIX specification.
+* Memory Barriers::	Preventing reordering of loads and stores.
 @end menu
 
 
@@ -763,6 +764,62 @@ Behaves like @code{pthread_timedjoin_np} except that the absolute time in
 @var{abstime} is measured against the clock specified by @var{clockid}.
 @end deftypefun
 
+@node Memory Barriers
+@section Memory Barriers
+@cindex barriers
+@cindex compiler barriers
+@cindex concurrency barriers
+@cindex fences
+@cindex memory barriers
+@cindex signal fences
+@cindex thread fences
+
+Barriers come in different forms: Compiler barriers and memory
+barriers.  Compiler barriers constrain how the compiler can reorder or
+optimize away memory accesses, affecting what instructions are emitted
+in which order.  Memory barriers affect how the CPU and the memory
+subsystem of a machine are allowed to optimize execution, controlling
+similar optimizations at the hardware layer.  Both kinds of barriers
+have a run-time cost.  For memory barriers, their cost depends on
+their strength (that is, how much hardware optimization they prevent),
+and how large the system is (e.g., how many CPUs have to coordinate
+for an effective barrier).
+
+Compiler barriers are called signal fences in ISO C, and memory
+barriers are called thread fences.  POSIX barriers (of type
+@code{pthread_barrier_t}) are only peripherally related to the
+barriers discussed here: using them for synchronization creates a
+memory barrier as a side effect.
+
+@deftypefun void atomic_signal_fence (memory_order @var{order})
+@standards{ISO, stdatomic.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+A compiler barrier.  Equivalent to the GCC built-in
+@code{__atomic_signal_fence (@var{order1})} if @var{order1} is the GCC
+variant of the memory order @var{order}.  @xref{__atomic Builtins,
+__atomic Builtins, Built-in Functions for Memory Model Aware Atomic
+Operations, gcc, The GNU Compiler Collection}.
+
+For example, @code{atomic_signal_fence (memory_order_acq_rel)} is
+equivalent to @code{__atomic_signal_fence (__ATOMIC_ACQ_REL)}.  Older
+code often writes this type of compiler barrier as @code{asm ("" :::
+"memory")} because the compiler cannot move loads and stores across
+this inline assembly construct because of the memory clobber.
+@end deftypefun
+
+@deftypefun void atomic_thread_fence (memory_order @var{order})
+@standards{ISO, stdatomic.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+A memory barrier.  Equivalent to the GCC built-in
+@code{__atomic_thread_fence (@var{order1})} if @var{order1} is the GCC
+variant of the memory order @var{order}.  @xref{__atomic Builtins,
+__atomic Builtins, Built-in Functions for Memory Model Aware Atomic
+Operations, gcc, The GNU Compiler Collection}.
+
+For example, @code{atomic_thread_fence (memory_order_acq_rel)} is
+equivalent to @code{__atomic_thread_fence (__ATOMIC_ACQ_REL)}.
+@end deftypefun
+
 @c FIXME these are undocumented:
 @c pthread_atfork
 @c pthread_attr_destroy

Re: [PATCH] manual: Document compiler and memory barriers

[Carlos O'Donell]

On 12/6/19 2:08 PM, Florian Weimer wrote:
> -----
>  manual/threads.texi | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 57 insertions(+)
> 
> diff --git a/manual/threads.texi b/manual/threads.texi
> index 0858ef8f92..23e22dcca9 100644
> --- a/manual/threads.texi
> +++ b/manual/threads.texi
> @@ -11,6 +11,7 @@ POSIX threads.
>  @menu
>  * ISO C Threads::	Threads based on the ISO C specification.
>  * POSIX Threads::	Threads based on the POSIX specification.
> +* Memory Barriers::	Preventing reordering of loads and stores.

You posted this patch without any rationale or commit message, was
this an accidental push to the mailing list?

>  @end menu
>  
>  
> @@ -763,6 +764,62 @@ Behaves like @code{pthread_timedjoin_np} except that the absolute time in
>  @var{abstime} is measured against the clock specified by @var{clockid}.
>  @end deftypefun
>  
> +@node Memory Barriers
> +@section Memory Barriers
> +@cindex barriers
> +@cindex compiler barriers
> +@cindex concurrency barriers
> +@cindex fences
> +@cindex memory barriers
> +@cindex signal fences
> +@cindex thread fences
> +
> +Barriers come in different forms: Compiler barriers and memory
> +barriers.  Compiler barriers constrain how the compiler can reorder or
> +optimize away memory accesses, affecting what instructions are emitted
> +in which order.  Memory barriers affect how the CPU and the memory
> +subsystem of a machine are allowed to optimize execution, controlling
> +similar optimizations at the hardware layer.  Both kinds of barriers
> +have a run-time cost.  For memory barriers, their cost depends on
> +their strength (that is, how much hardware optimization they prevent),
> +and how large the system is (e.g., how many CPUs have to coordinate
> +for an effective barrier).
> +
> +Compiler barriers are called signal fences in ISO C, and memory
> +barriers are called thread fences.  POSIX barriers (of type
> +@code{pthread_barrier_t}) are only peripherally related to the
> +barriers discussed here: using them for synchronization creates a
> +memory barrier as a side effect.
> +
> +@deftypefun void atomic_signal_fence (memory_order @var{order})
> +@standards{ISO, stdatomic.h}
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +A compiler barrier.  Equivalent to the GCC built-in
> +@code{__atomic_signal_fence (@var{order1})} if @var{order1} is the GCC
> +variant of the memory order @var{order}.  @xref{__atomic Builtins,
> +__atomic Builtins, Built-in Functions for Memory Model Aware Atomic
> +Operations, gcc, The GNU Compiler Collection}.
> +
> +For example, @code{atomic_signal_fence (memory_order_acq_rel)} is
> +equivalent to @code{__atomic_signal_fence (__ATOMIC_ACQ_REL)}.  Older
> +code often writes this type of compiler barrier as @code{asm ("" :::
> +"memory")} because the compiler cannot move loads and stores across
> +this inline assembly construct because of the memory clobber.
> +@end deftypefun
> +
> +@deftypefun void atomic_thread_fence (memory_order @var{order})
> +@standards{ISO, stdatomic.h}
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +A memory barrier.  Equivalent to the GCC built-in
> +@code{__atomic_thread_fence (@var{order1})} if @var{order1} is the GCC
> +variant of the memory order @var{order}.  @xref{__atomic Builtins,
> +__atomic Builtins, Built-in Functions for Memory Model Aware Atomic
> +Operations, gcc, The GNU Compiler Collection}.
> +
> +For example, @code{atomic_thread_fence (memory_order_acq_rel)} is
> +equivalent to @code{__atomic_thread_fence (__ATOMIC_ACQ_REL)}.
> +@end deftypefun
> +
>  @c FIXME these are undocumented:
>  @c pthread_atfork
>  @c pthread_attr_destroy
> 


-- 
Cheers,
Carlos.

Re: [PATCH] manual: Document compiler and memory barriers

[Florian Weimer]

* Carlos O'Donell:

> You posted this patch without any rationale or commit message, was
> this an accidental push to the mailing list?

Do we need a rationale for more documentation? 8-)

Parts of <stddef.h> are already covered in the manual, even though the
header is provided by GCC (like <stdatomic.h>).

I want to reference this documentation in them membarrier patch.

Re: [PATCH] manual: Document compiler and memory barriers

[Carlos O'Donell]

On 12/7/19 8:22 AM, Florian Weimer wrote:
> * Carlos O'Donell:
> 
>> You posted this patch without any rationale or commit message, was
>> this an accidental push to the mailing list?
> 
> Do we need a rationale for more documentation? 8-)

No, not at all! ;-)

The problem with "no rationale" is that I can't disambiguate between
that and other possible problem states.

> Parts of <stddef.h> are already covered in the manual, even though the
> header is provided by GCC (like <stdatomic.h>).
> 
> I want to reference this documentation in them membarrier patch.
> 

Ah! That's *exactly* the rationale I was looking for :-)

-- 
Cheers,
Carlos.

Re: [PATCH] manual: Document compiler and memory barriers

[Rafal Luzynski]

6.12.2019 20:08 Florian Weimer <fweimer@redhat.com> wrote:
> [...]
> +their strength (that is, how much hardware optimization they prevent),
> +and how large the system is (e.g., how many CPUs have to coordinate

AFAIK "e.g.," should be "e.g.,@:" to avoid a long space which should
normally be used between sentences.

This is not a complete review, sadly I can't do it.

Regards,

Rafal

Re: [PATCH] manual: Document compiler and memory barriers

[Florian Weimer]

* Rafal Luzynski:

> 6.12.2019 20:08 Florian Weimer <fweimer@redhat.com> wrote:
>> [...]
>> +their strength (that is, how much hardware optimization they prevent),
>> +and how large the system is (e.g., how many CPUs have to coordinate
>
> AFAIK "e.g.," should be "e.g.,@:" to avoid a long space which should
> normally be used between sentences.

I think the Texinfo manual is incomplete.  Clearly this does not happen
for all such periods, only those that are followed by whitespace in some
sense.  It's not easy to infer this from the Texinfo sources, but I
think that . ? ! followed by any of " ' ) ] (, possibly with repeats,
followed by whitespace causes that whitespace to be widened.  So “e.g.,”
should be fine on its own.

Thanks,
Florian

Re: [PATCH] manual: Document compiler and memory barriers

[Andreas Schwab]

On Dez 12 2019, Florian Weimer wrote:

> It's not easy to infer this from the Texinfo sources, but I think that
> . ? ! followed by any of " ' ) ] (, possibly with repeats, followed by
> whitespace causes that whitespace to be widened.

Only characters with \sfcode > 0 change the \spacefactor.

Andreas.

-- 
Andreas Schwab, SUSE Labs, schwab@suse.de
GPG Key fingerprint = 0196 BAD8 1CE9 1970 F4BE  1748 E4D4 88E3 0EEA B9D7
"And now for something completely different."

Re: [PATCH] manual: Document compiler and memory barriers

[Rafal Luzynski]

12.12.2019 13:41 Florian Weimer <fweimer@redhat.com> wrote:
> 
> * Rafal Luzynski:
> 
> > [...]
> > AFAIK "e.g.," should be "e.g.,@:" to avoid a long space which should
> > normally be used between sentences.
> 
> I think the Texinfo manual is incomplete.  Clearly this does not happen
> for all such periods, only those that are followed by whitespace in some
> sense.  It's not easy to infer this from the Texinfo sources, but I
> think that . ? ! followed by any of " ' ) ] (, possibly with repeats,
> followed by whitespace causes that whitespace to be widened.  So “e.g.,”
> should be fine on its own.

I am not an expert but I was told this here:

https://sourceware.org/ml/libc-alpha/2017-10/msg01302.html

Also I think I did some tests by that time and indeed there was a difference
in the PDF version.  But maybe my memory is bad.

Regards,

Rafal

Re: [PATCH] manual: Document compiler and memory barriers

[Florian Weimer]

* Rafal Luzynski:

> 12.12.2019 13:41 Florian Weimer <fweimer@redhat.com> wrote:
>> 
>> * Rafal Luzynski:
>> 
>> > [...]
>> > AFAIK "e.g.," should be "e.g.,@:" to avoid a long space which should
>> > normally be used between sentences.
>> 
>> I think the Texinfo manual is incomplete.  Clearly this does not happen
>> for all such periods, only those that are followed by whitespace in some
>> sense.  It's not easy to infer this from the Texinfo sources, but I
>> think that . ? ! followed by any of " ' ) ] (, possibly with repeats,
>> followed by whitespace causes that whitespace to be widened.  So “e.g.,”
>> should be fine on its own.
>
> I am not an expert but I was told this here:
>
> https://sourceware.org/ml/libc-alpha/2017-10/msg01302.html
>
> Also I think I did some tests by that time and indeed there was a difference
> in the PDF version.  But maybe my memory is bad.

I just tried it, and I don't see a difference in following whitespace
between “e.g.,” and e.g.,@:”.

Thanks,
Florian

Re: [PATCH] manual: Document compiler and memory barriers

[Rafal Luzynski]

18.12.2019 11:08 Florian Weimer <fweimer@redhat.com> wrote:
> [...]
> I just tried it, and I don't see a difference in following whitespace
> between “e.g.,” and e.g.,@:”.

OK, I trust you and I withdraw my objection.

Regards,

Rafal