From patchwork Wed May 20 18:12:59 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Florian Weimer X-Patchwork-Id: 39345 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 68435395B80B; Wed, 20 May 2020 18:13:07 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 68435395B80B DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1589998387; bh=f4bfBoRsTH3zCBeXyKh5u46lTeatYrFAhtsjfxEKzT8=; h=To:Subject:In-Reply-To:References:Date:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To:Cc: From; b=HHuXCMczYrOvvsxK/A5eNQ89p2tAjaLMU3St9xvnjj1QYJLBWuu0HJ653qRxBOG4Q x+bS4bicJN9C/KeIWq23yy95/2ATkQl67sgZb90D8O0Xvxexb02ByZcPY9Qe4xbAIS VxLzBxYYbudbiKR286pV0EL6xuuNLJKsbLPJe7q4= X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org Received: from us-smtp-delivery-1.mimecast.com (us-smtp-1.mimecast.com [205.139.110.61]) by sourceware.org (Postfix) with ESMTP id 52017385DC32 for ; Wed, 20 May 2020 18:13:04 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org 52017385DC32 Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-204-XK-E0QyvM2Ch5gnxCfR7Hw-1; Wed, 20 May 2020 14:13:02 -0400 X-MC-Unique: XK-E0QyvM2Ch5gnxCfR7Hw-1 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.phx2.redhat.com [10.5.11.22]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 4D651835B40; Wed, 20 May 2020 18:13:01 +0000 (UTC) Received: from oldenburg2.str.redhat.com (ovpn-113-191.ams2.redhat.com [10.36.113.191]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 979E010640E1; Wed, 20 May 2020 18:13:00 +0000 (UTC) To: libc-alpha@sourceware.org Subject: [PATCH 2/2] manual: Document __libc_single_threaded In-Reply-To: References: Message-Id: <2c218c9ed9586ed5491f6fa08045d1e883b126c3.1589998207.git.fweimer@redhat.com> Date: Wed, 20 May 2020 20:12:59 +0200 User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.3 (gnu/linux) MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.22 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-14.0 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H2, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.2 X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on server2.sourceware.org X-BeenThere: libc-alpha@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Libc-alpha mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Florian Weimer via Libc-alpha From: Florian Weimer Reply-To: Florian Weimer Cc: Michael Kerrisk Errors-To: libc-alpha-bounces@sourceware.org Sender: "Libc-alpha" --- manual/threads.texi | 89 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) diff --git a/manual/threads.texi b/manual/threads.texi index a425635179..d4c261a0e9 100644 --- a/manual/threads.texi +++ b/manual/threads.texi @@ -627,6 +627,7 @@ the standard. threads in a process. * Waiting with Explicit Clocks:: Functions for waiting with an explicit clock specification. +* Single-Threaded:: Detecting single-threaded execution. @end menu @node Default Thread Attributes @@ -771,6 +772,94 @@ 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 Single-Threaded +@subsubsection Detecting Single-Threaded Execution + +Multi-threaded programs require synchronization among threads. This +synchronization can be costly even if there is just a single thread +and no data is shared between multiple processors. @Theglibc{} offers +an interface to detect whether the process is in single-threaded mode. +Applications can use this information to avoid synchronization, for +example by using regular instructions to load and store memory instead +of atomic instructions, or using relaxed memory ordering instead of +stronger memory ordering. + +@deftypevar char __libc_single_threaded +@standards{GNU, sys/single_threaded.h} +This variable is non-zero if the current process is definitely +single-threaded. If it is zero, the process can be multi-threaded, +or @theglibc{} cannot determine at this point of the program execution +whether the process is single-threaded or not. + +Applications must never write to this variable. +@end deftypevar + +Most applications should perform the same actions whether or not +@code{__libc_single_threaded} is true, except with less +synchronization. If this rule is followed, a process that +subsequently becomes multi-threaded is already in a consistent state. +For example, in order to increment a reference count, the following +code can be used: + +@smallexample +if (__libc_single_threaded) + atomic_fetch_add (&reference_count, 1, memory_order_relaxed); +else + atomic_fetch_add (&reference_count, 1, memory_order_acq_rel); +@end smallexample + +This still requires some form of synchronization on the +single-threaded branch, so it can be beneficial not to declare the +reference count as @code{_Atomic}, and use the GCC @code{__atomic} +built-ins. @xref{__atomic Builtins,, Built-in Functions for Memory +Model Aware Atomic Operations, gcc, Using the GNU Compiler Collection +(GCC)}. Then the code to increment a reference count looks like this: + +@smallexample +if (__libc_single_threaded) + ++refeference_count;inf +else + __atomic_fetch_add (&reference_count, 1, __ATOMIC_ACQ_REL); +@end smallexample + +(Depending on the data associated with the reference count, it may be +possible to use the weaker @code{__ATOMIC_RELAXED} memory ordering on +the multi-threaded branch.) + +Several functions in @theglibc{} can change the value of the +@code{__libc_single_threaded} variable. For example, creating new +threads using the @code{pthread_create} or @code{thrd_create} function +sets the variable to false. This can also happen directly, say via a +call to @code{dlopen}. Therefore, applications need to make a copy of +the value of @code{__libc_single_threaded} if after such a function +call, behavior must match the value as it was before the call, like +this: + +@smallexample +bool single_threaded = __libc_single_threaded; +if (single_threaded) + prepare_single_threaded (); +else + prepare_multi_thread (); + +void *handle = dlopen (shared_library_name, RTLD_NOW); +lookup_symbols (handle); + +if (single_threaded) + cleanup_single_threaded (); +else + cleanup_multi_thread (); +@end smallexample + +Since the value of @code{__libc_single_threaded} can change from true +to false during the execution of the program, it is not useful for +selecting optimized function implementations in IFUNC resolvers. + +Atomic operations can also be used on mappings shared among +single-threaded processes. This means that a compiler cannot use +@code{__libc_single_threaded} to optimize atomic operations, unless it +is able to prove that the memory is not shared. + @c FIXME these are undocumented: @c pthread_atfork @c pthread_attr_destroy