From nobody Fri Oct 08 00:46:40 2021 X-Original-To: dev-commits-src-branches@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 68E0A17EBFFE; Fri, 8 Oct 2021 00:46:41 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4HQTz50B8Kz3pj9; Fri, 8 Oct 2021 00:46:41 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id CCF7F1DC0E; Fri, 8 Oct 2021 00:46:40 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 1980kenb069949; Fri, 8 Oct 2021 00:46:40 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 1980keeI069948; Fri, 8 Oct 2021 00:46:40 GMT (envelope-from git) Date: Fri, 8 Oct 2021 00:46:40 GMT Message-Id: <202110080046.1980keeI069948@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: Konstantin Belousov Subject: git: d90db5033848 - stable/12 - libthr(3): explain some internals of the locks implementation List-Id: Commits to the stable branches of the FreeBSD src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-branches List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-src-branches@freebsd.org X-BeenThere: dev-commits-src-branches@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: kib X-Git-Repository: src X-Git-Refname: refs/heads/stable/12 X-Git-Reftype: branch X-Git-Commit: d90db5033848d11f5f8a8542acbbaef663e6eabb Auto-Submitted: auto-generated X-ThisMailContainsUnwantedMimeParts: N The branch stable/12 has been updated by kib: URL: https://cgit.FreeBSD.org/src/commit/?id=d90db5033848d11f5f8a8542acbbaef663e6eabb commit d90db5033848d11f5f8a8542acbbaef663e6eabb Author: Konstantin Belousov AuthorDate: 2021-10-01 01:17:02 +0000 Commit: Konstantin Belousov CommitDate: 2021-10-08 00:46:21 +0000 libthr(3): explain some internals of the locks implementation (cherry picked from commit f5b9747075a9b489226e2a911f8a1597f4b9d072) --- lib/libthr/libthr.3 | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 61 insertions(+), 2 deletions(-) diff --git a/lib/libthr/libthr.3 b/lib/libthr/libthr.3 index 6828a6e7d43b..201a21307f04 100644 --- a/lib/libthr/libthr.3 +++ b/lib/libthr/libthr.3 @@ -1,5 +1,5 @@ .\" Copyright (c) 2005 Robert N. M. Watson -.\" Copyright (c) 2014,2015 The FreeBSD Foundation, Inc. +.\" Copyright (c) 2014,2015,2021 The FreeBSD Foundation, Inc. .\" All rights reserved. .\" .\" Part of this documentation was written by @@ -29,7 +29,7 @@ .\" .\" $FreeBSD$ .\" -.Dd May 17, 2016 +.Dd October 1, 2021 .Dt LIBTHR 3 .Os .Sh NAME @@ -259,6 +259,65 @@ the critical section. This should be taken into account when interpreting .Xr ktrace 1 logs. +.Sh PROCESS-SHARED SYNCHRONIZATION OBJECTS +In the +.Li libthr +implementation, +user-visible types for all synchronization objects (e.g. pthread_mutex_t) +are pointers to internal structures, allocated either by the corresponding +.Fn pthread__init +method call, or implicitly on first use when a static initializer +was specified. +The initial implementation of process-private locking object used this +model with internal allocation, and the addition of process-shared objects +was done in a way that did not break the application binary interface. +.Pp +For process-private objects, the internal structure is allocated using +either +.Xr malloc 3 +or, for +.Xr pthread_mutex_init 3 , +an internal memory allocator implemented in +.Nm . +The internal allocator for mutexes is used to avoid bootstrap issues +with many +.Xr malloc 3 +implementations which need working mutexes to function. +The same allocator is used for thread-specific data, see +.Xr pthread_setspecific 3 , +for the same reason. +.Pp +For process-shared objects, the internal structure is created by first +allocating a shared memory segment using +.Xr _umtx_op 2 +operation +.Dv UMTX_OP_SHM , +and then mapping it into process address space with +.Xr mmap 2 +with the +.Dv MAP_SHARED +flag. +The POSIX standard requires that: +.Bd -literal +only the process-shared synchronization object itself can be used for +performing synchronization. It need not be referenced at the address +used to initialize it (that is, another mapping of the same object can +be used). +.Ed +.Pp +With the +.Fx +implementation, process-shared objects require initialization +in each process that use them. +In particular, if you map the shared memory containing the user portion of +a process-shared object already initialized in different process, locking +functions do not work on it. +.Pp +Another broken case is a forked child creating the object in memory shared +with the parent, which cannot be used from parent. +Note that processes should not use non-async-signal safe functions after +.Xr fork 2 +anyway. .Sh SEE ALSO .Xr ktrace 1 , .Xr ld-elf.so.1 1 ,