From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from us-smtp-1.mimecast.com (us-smtp-1.mimecast.com [207.211.31.81]) by sourceware.org (Postfix) with ESMTP id D946C3858D37 for ; Tue, 30 Jun 2020 01:06:26 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org D946C3858D37 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-153-_j3IpW61NsOvJzGfMylYUw-1; Mon, 29 Jun 2020 21:06:24 -0400 X-MC-Unique: _j3IpW61NsOvJzGfMylYUw-1 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 576261005512; Tue, 30 Jun 2020 01:06:23 +0000 (UTC) Received: from greed.delorie.com (ovpn-112-69.phx2.redhat.com [10.3.112.69]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 2C62F5BAEC; Tue, 30 Jun 2020 01:06:23 +0000 (UTC) Received: from greed.delorie.com.redhat.com (localhost [127.0.0.1]) by greed.delorie.com (8.14.7/8.14.7) with ESMTP id 05U16Lve025063; Mon, 29 Jun 2020 21:06:22 -0400 From: DJ Delorie To: Florian Weimer Cc: libc-alpha@sourceware.org, mtk.manpages@gmail.com Subject: Re: [PATCH v2 2/2] manual: Document __libc_single_threaded In-Reply-To: <99b00049f399fd0acffb2c27530f8fd7a64018f8.1593003514.git.fweimer@redhat.com> (message from Florian Weimer via Libc-alpha on Wed, 24 Jun 2020 15:03:55 +0200) Date: Mon, 29 Jun 2020 21:06:21 -0400 Message-ID: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain X-Spam-Status: No, score=-8.3 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H3, RCVD_IN_MSPIKE_WL, 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-List-Received-Date: Tue, 30 Jun 2020 01:06:28 -0000 LGTM but one optional wording change near the end. Reviewed-by: DJ Delorie Florian Weimer via Libc-alpha writes: > +* Single-Threaded:: Detecting single-threaded execution. Ok. > @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 may 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 Ok. > +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: Ok. > +@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 Ok. > +@c Note: No memory order on __libc_single_threaded. The > +@c implementation must ensure that exit of the critical > +@c (second-to-last) thread happens-before setting > +@c __libc_single_threaded to true. Otherwise, acquire MO might be > +@c needed for reading the variable in some scenarios, and that would > +@c completely defeat its purpose. > + > +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; > +else > + __atomic_fetch_add (&reference_count, 1, __ATOMIC_ACQ_REL); > +@end smallexample Ok. > +(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 indirectly, 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 Ok. > +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. Ok. > +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. Ok. "must not" would be slightly more correct than "cannot" though. > +@strong{Implementation Note:} The @code{__libc_single_threaded} > +variable is not declared as @code{volatile} because it is expected > +that compilers optimize a sequence of single-threaded checks into one > +check, for example if several reference counts are updated. The > +current implementation in @theglibc{} does not set the > +@code{__libc_single_threaded} variable to a true value if a process > +turns single-threaded again. Future versions of @theglibc{} may do > +this, but only as the result of function calls which imply an acquire > +(compiler) barrier. (Some compilers assume that well-known functions > +such as @code{malloc} do not write to global variables, and setting > +@code{__libc_single_threaded} would introduce a data race and > +undefined behavior.) In any case, an application must not write to > +@code{__libc_single_threaded} even if it has joined the last > +application-created thread because future versions of @theglibc{} may > +create background threads after the first thread has been created, and > +the application has no way of knowning that these threads are present. > + > @c FIXME these are undocumented: > @c pthread_atfork > @c pthread_attr_destroy Ok.