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

[Carlos O'Donell <codonell at redhat dot com>]

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.