-
The current design handles the most common use-cases, although it causes breakage on others (when a pthreads liked library is dlopened). Refer to the README for further details. The new design, makes pthread-stubs a "meta" package which _never_ provides a library but only a .pc file. pthread-stubs checks if the run-time (libc or otherwise) expose lightweight pthread symbols to link against and defaults to a full blown pthread. This way projects can use the Cflags/Libs without having to know the details. Alternatively they can directly link against the pthread implementation, although that might bring unwarranted overhead. v2: - Remove m4 macro, always use -pthread and document why. - Sort the symbol list, document how it's derived what is allowed and what not. - Rework the README to start from current state of afairs to past ones. - Document platforms that are 'safe' and ones that are not. v3: - Add SVN note about -pthread + Cygwin/mingw/mingw-w64 Signed-off-by:
Emil Velikov <emil.velikov@collabora.com> Acked-by:
Eric Anholt <eric@anholt.net> Signed-off-by:
Uli Schlachter <psychon@znc.in>
The current design handles the most common use-cases, although it causes breakage on others (when a pthreads liked library is dlopened). Refer to the README for further details. The new design, makes pthread-stubs a "meta" package which _never_ provides a library but only a .pc file. pthread-stubs checks if the run-time (libc or otherwise) expose lightweight pthread symbols to link against and defaults to a full blown pthread. This way projects can use the Cflags/Libs without having to know the details. Alternatively they can directly link against the pthread implementation, although that might bring unwarranted overhead. v2: - Remove m4 macro, always use -pthread and document why. - Sort the symbol list, document how it's derived what is allowed and what not. - Rework the README to start from current state of afairs to past ones. - Document platforms that are 'safe' and ones that are not. v3: - Add SVN note about -pthread + Cygwin/mingw/mingw-w64 Signed-off-by:
README 3.38 KiB
Project description ------------------- Currently the project provides only a pkg-config [.pc] file, pthread-stubs.pc. The latter contains the Cflags/Libs flags applicable to programs/libraries that use only lightweight pthread API. See the next sections for the reasoning and implementation details. Historically this project used to provide either: - a .pc file, when the C runtime was providing the pthread symbols or - a .pc file and a library which implements weak stubs for the pthread symbols, which are not available in the C runtime. Since then, the latter case was found to have a fundamental design issue. Design ------ On platforms where the lightweight pthread symbols are provided by the runtime, the .pc files provides empty Cflags/Libs flags. Currently the following platforms fit the above category: - GNU/Linux - GCC/Clang/GLibC/Musl - Solaris 10 and later - Cygwin - GNU/Hurd - GNU/kFreeBSD For others, each of Cflags/Libs expands to full blown pthread. For example: - FreeBSD and derivatives - OpenBSD - uses a heavily patched copy of pthread-stubs to workaround this - other BSD platforms ? Unchecked: - MSYS/MINGW - Darwin - GCC/Clang - should be the same as their Linux counter part Many platforms have their own eccentric way of managing pthread compilation and linkage. The ones realistically supported by pthread-stubs [and projects that depend on it] work with '-pthread'. GCC supports -pthread for: Aarch64, ARM, Darwin, IA-64, MIPS, PowerPC, SPARC, x86 Cygwin and x86 Windows may need a trivial patch for older GCC versions. See SVN rev 214161 and 171833/171834 respectively. Clang: Aarch64, ARM, x86 and likely others. SunCC/Oracle compiler: Requires -mt -lpthread. As of Solaris 10 (oldest currently supported version) all the pthread API lives in libc. Thus we'll _never_ get here. With previous design, one could get mismatched calls to the pthreads API. Consider the following scenario: - Program and/or its dependencies links only against libpthread-stubs, since it uses lightweight API. Say pthread_mutex_lock. - At a later stage the program and/or its dependencies dlopens a library which effectively [either directly or via any of its own dependencies] pulls a full blown pthread. Let's call that libB. - The libpthread-stubs weak symbols get overridden by the libB ones. - pthread_mutex_unlock is executed (which now originates from libB) and BOOM. Amount and severity of issues depend on a number of factors. In either case things go horribly wrong sooner on later. The symbols ----------- The following list of symbols is taken from the libc provided by GLibC. It is deemed sufficient and reasonably accurate of what the 'lightweight' pthread symbols are, since GLibC is one of the few (the only) implementations which has the distinct split. Most/all other C runtime implementations provide all the pthread API in a single library. Note that the following list is incomplete wrt libc-2.24.so and that further symbols may be added in the future to bring the two closer. Adding symbols which are not available in GLibC libc is NOT allowed. pthread_condattr_destroy pthread_condattr_init pthread_cond_broadcast pthread_cond_destroy pthread_cond_init pthread_cond_signal pthread_cond_timedwait pthread_cond_wait pthread_equal pthread_exit pthread_mutex_destroy pthread_mutex_init pthread_mutex_lock pthread_mutex_unlock pthread_self