Changeset View
Changeset View
Standalone View
Standalone View
lib/libthr/libthr.3
.\" Copyright (c) 2005 Robert N. M. Watson | .\" 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. | .\" All rights reserved. | ||||||||||
.\" | .\" | ||||||||||
.\" Part of this documentation was written by | .\" Part of this documentation was written by | ||||||||||
.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship | .\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship | ||||||||||
.\" from the FreeBSD Foundation. | .\" from the FreeBSD Foundation. | ||||||||||
.\" | .\" | ||||||||||
.\" Redistribution and use in source and binary forms, with or without | .\" Redistribution and use in source and binary forms, with or without | ||||||||||
.\" modification, are permitted provided that the following conditions | .\" modification, are permitted provided that the following conditions | ||||||||||
Show All 13 Lines | |||||||||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | ||||||||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | ||||||||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | ||||||||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | ||||||||||
.\" SUCH DAMAGE. | .\" SUCH DAMAGE. | ||||||||||
.\" | .\" | ||||||||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||||||||
.\" | .\" | ||||||||||
.Dd May 5, 2020 | .Dd October 1, 2021 | ||||||||||
.Dt LIBTHR 3 | .Dt LIBTHR 3 | ||||||||||
.Os | .Os | ||||||||||
.Sh NAME | .Sh NAME | ||||||||||
.Nm libthr | .Nm libthr | ||||||||||
.Nd "1:1 POSIX threads library" | .Nd "1:1 POSIX threads library" | ||||||||||
.Sh LIBRARY | .Sh LIBRARY | ||||||||||
.Lb libthr | .Lb libthr | ||||||||||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||||||||||
▲ Show 20 Lines • Show All 213 Lines • ▼ Show 20 Lines | |||||||||||
of the user-provided signal handler is unsafe. | of the user-provided signal handler is unsafe. | ||||||||||
An example of such a situation is owning the internal library lock. | An example of such a situation is owning the internal library lock. | ||||||||||
When a signal is delivered while the signal handler cannot be safely | When a signal is delivered while the signal handler cannot be safely | ||||||||||
called, the call is postponed and performed until after the exit from | called, the call is postponed and performed until after the exit from | ||||||||||
the critical section. | the critical section. | ||||||||||
This should be taken into account when interpreting | This should be taken into account when interpreting | ||||||||||
.Xr ktrace 1 | .Xr ktrace 1 | ||||||||||
logs. | logs. | ||||||||||
.Sh PROCESS-SHARED SYNCHRONIZATION OBJECTS | |||||||||||
In the | |||||||||||
.Li libthr | |||||||||||
implementation, | |||||||||||
user-visible types for all synchronization objects (e.g. pthread_mutex_t) | |||||||||||
markj: Maybe "all synchronization objects (e.g., pthread_mutex_t) ..." | |||||||||||
Done Inline Actions
markj: | |||||||||||
are pointers to internal structures, allocated either by the corresponding | |||||||||||
Done Inline Actions
markj: | |||||||||||
.Fn pthread_<objtype>_init | |||||||||||
method call, or implicitly on first use when a static initializer | |||||||||||
Done Inline Actions
markj: | |||||||||||
was specified. | |||||||||||
The initial implementation of process-private locking object used this | |||||||||||
Done Inline Actions
markj: | |||||||||||
model with internal allocation, and the addition of process-shared objects | |||||||||||
Done Inline Actions
markj: | |||||||||||
was done in a way that did not break the application binary interface. | |||||||||||
Done Inline Actions
markj: | |||||||||||
.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 | |||||||||||
Done Inline Actions
markj: | |||||||||||
.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 | |||||||||||
Done Inline Actions
markj: | |||||||||||
.Xr _umtx_op 2 | |||||||||||
operation | |||||||||||
.Dv UMTX_OP_SHM , | |||||||||||
and then mapping it into process address space with | |||||||||||
.Xr mmap 2 | |||||||||||
with | |||||||||||
Done Inline Actions
Reads better like jilles: Reads better like | |||||||||||
.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 initalize it (that is, another mapping of the same object can | |||||||||||
jillesUnsubmitted Done Inline Actions
typo jilles: typo | |||||||||||
be used). | |||||||||||
.Ed | |||||||||||
.Pp | |||||||||||
With the | |||||||||||
Done Inline ActionsMaybe s/this/the FreeBSD/, assuming I understood correctly. markj: Maybe s/this/the FreeBSD/, assuming I understood correctly. | |||||||||||
Done Inline Actions
markj: | |||||||||||
.Fx | |||||||||||
implementation, process-shared objects require initialization | |||||||||||
in each process that use them. | |||||||||||
Done Inline Actions
markj: | |||||||||||
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 | .Sh SEE ALSO | ||||||||||
.Xr ktrace 1 , | .Xr ktrace 1 , | ||||||||||
.Xr ld-elf.so.1 1 , | .Xr ld-elf.so.1 1 , | ||||||||||
.Xr getrlimit 2 , | .Xr getrlimit 2 , | ||||||||||
.Xr errno 2 , | .Xr errno 2 , | ||||||||||
.Xr thr_exit 2 , | .Xr thr_exit 2 , | ||||||||||
.Xr thr_kill 2 , | .Xr thr_kill 2 , | ||||||||||
.Xr thr_kill2 2 , | .Xr thr_kill2 2 , | ||||||||||
Show All 30 Lines |
Maybe "all synchronization objects (e.g., pthread_mutex_t) ..."