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