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