1Project description
2-------------------
3
4Currently the project provides only a pkg-config [.pc] file, pthread-stubs.pc.
5The latter contains the Cflags/Libs flags applicable to programs/libraries
6that use only lightweight pthread API. See the next sections for the reasoning
7and implementation details.
8
9Historically this project used to provide either:
10 - a .pc file, when the C runtime was providing the pthread symbols
11or
12 - a .pc file and a library which implements weak stubs for the pthread symbols,
13which are not available in the C runtime.
14
15Since then, the latter case was found to have a fundamental design issue.
16
17
18Design
19------
20
21On platforms where the lightweight pthread symbols are provided by the runtime,
22the .pc files provides empty Cflags/Libs flags.
23
24Currently the following platforms fit the above category:
25 - GNU/Linux - GCC/Clang/GLibC/Musl
26 - Solaris 10 and later
27 - Cygwin
28 - GNU/Hurd
29 - GNU/kFreeBSD
30
31For others, each of Cflags/Libs expands to full blown pthread.
32
33For example:
34 - FreeBSD and derivatives
35 - OpenBSD - uses a heavily patched copy of pthread-stubs to workaround this
36 - other BSD platforms ?
37
38Unchecked:
39 - MSYS/MINGW
40 - Darwin - GCC/Clang - should be the same as their Linux counter part
41
42
43Many platforms have their own eccentric way of managing pthread compilation and
44linkage. The ones realistically supported by pthread-stubs [and projects that
45depend on it] work with '-pthread'.
46
47GCC supports -pthread for:
48Aarch64, ARM, Darwin, IA-64, MIPS, PowerPC, SPARC, x86
49Cygwin and x86 Windows may need a trivial patch for older GCC versions.
50See SVN rev 214161 and 171833/171834 respectively.
51
52
53Clang:
54Aarch64, ARM, x86 and likely others.
55
56SunCC/Oracle compiler:
57Requires -mt -lpthread. As of Solaris 10 (oldest currently supported version)
58all the pthread API lives in libc. Thus we'll _never_ get here.
59
60
61With previous design, one could get mismatched calls to the pthreads API.
62Consider the following scenario:
63 - Program and/or its dependencies links only against libpthread-stubs,
64since it uses lightweight API. Say pthread_mutex_lock.
65 - At a later stage the program and/or its dependencies dlopens a library
66which effectively [either directly or via any of its own dependencies] pulls a
67full blown pthread. Let's call that libB.
68 - The libpthread-stubs weak symbols get overridden by the libB ones.
69 - pthread_mutex_unlock is executed (which now originates from libB) and BOOM.
70
71Amount and severity of issues depend on a number of factors. In either case
72things go horribly wrong sooner on later.
73
74
75The symbols
76-----------
77
78The following list of symbols is taken from the libc provided by GLibC.
79
80It is deemed sufficient and reasonably accurate of what the 'lightweight'
81pthread symbols are, since GLibC is one of the few (the only) implementations
82which has the distinct split.
83
84Most/all other C runtime implementations provide all the pthread API in a
85single library.
86
87Note that the following list is incomplete wrt libc-2.24.so and that further
88symbols may be added in the future to bring the two closer. Adding symbols
89which are not available in GLibC libc is NOT allowed.
90
91   pthread_condattr_destroy
92   pthread_condattr_init
93   pthread_cond_broadcast
94   pthread_cond_destroy
95   pthread_cond_init
96   pthread_cond_signal
97   pthread_cond_timedwait
98   pthread_cond_wait
99   pthread_equal
100   pthread_exit
101   pthread_mutex_destroy
102   pthread_mutex_init
103   pthread_mutex_lock
104   pthread_mutex_unlock
105   pthread_self
106