[PATCH] manual: Document compiler and memory barriers

[Florian Weimer <fweimer at redhat dot com>]

-----
 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