From patchwork Fri Dec 6 19:08:54 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Florian Weimer X-Patchwork-Id: 36574 Received: (qmail 37864 invoked by alias); 6 Dec 2019 19:09:02 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Delivered-To: mailing list libc-alpha@sourceware.org Received: (qmail 37853 invoked by uid 89); 6 Dec 2019 19:09:01 -0000 Authentication-Results: sourceware.org; auth=none X-Spam-SWARE-Status: No, score=-18.6 required=5.0 tests=AWL, BAYES_00, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, SPF_PASS autolearn=ham version=3.3.1 spammy=layer, menu X-HELO: us-smtp-delivery-1.mimecast.com DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1575659339; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=4bghEyiHMHOvlw4W8WZZIZGmIZ/7lRE4/L9X4axk/eA=; b=hhIaFQzJcCMjrldk/vdfEwiEthHfqJJABG+XJIcZbIlYu4IKuL571WDjZKWjpQxPP9A9Jd QOiKKjXuDdKwKvulTGqasmCZHW8Mxtl4DpGsMyIYLnZA1TkKpc2uXWszHZLVmWSvQ36G38 OOb44NxQtUeNxfaQ2MJoZUX7lXPWrkc= From: Florian Weimer To: libc-alpha@sourceware.org Subject: [PATCH] manual: Document compiler and memory barriers Date: Fri, 06 Dec 2019 20:08:54 +0100 Message-ID: <87sglxclvd.fsf@oldenburg2.str.redhat.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.2 (gnu/linux) MIME-Version: 1.0 X-Mimecast-Spam-Score: 0 ----- 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