20fa307449
Add sys/_pthreadtypes.h to allow compilation on FreeBSD >= 6.0. Initialize signal trampoline variables earlier to avoid race in wrapper around sigaction. Fix known API wrapper bugs. Port compile time options: Add option for using an alternate restart signal instead of SIGUSR2. Add options for adjustment of maximum thread stack size and maximum number of threads. Make all options start with LINUXTHREADS_ Note that complete FreeBSD source matching userland must be installed in /usr/src when compiling this port.
161 lines
7.3 KiB
Text
161 lines
7.3 KiB
Text
Some brief notes:
|
|
|
|
1) This package is intended to run on FreeBSD 5.0-current or FreeBSD 4.X, i386
|
|
processors only.
|
|
|
|
Do not use libc_r with the linuxthreads port, and do not compile/link with the
|
|
-pthread option (which pulls in libc_r). Rather, link with libc (which you will
|
|
get by default).
|
|
|
|
Compile your applications that use the linuxthreads port with the following
|
|
command line options:
|
|
|
|
-D_THREAD_SAFE -I/usr/local/include/pthread/linuxthreads -llthread -llgcc_r
|
|
|
|
Note that the include (-I<path>) directive shown here should appear before any
|
|
other include directive that would cause the compiler to find the FreeBSD file
|
|
/usr/include/pthread.h. Using the FreeBSD pthread.h instead of the linuxthreads
|
|
pthread.h will result in an app that fails in many odd and maybe spectacular
|
|
ways.
|
|
|
|
In order to facilitate porting applications which expect a libpthread, you can
|
|
create the following symlinks if you want:
|
|
|
|
ln -s /usr/local/lib/liblthread.a /usr/lib/libpthread.a
|
|
ln -s /usr/local/lib/liblthread_p.a /usr/lib/libpthread_p.a
|
|
ln -s /usr/local/lib/liblthread.so.2 /usr/lib/libpthread.so.2
|
|
ln -s /usr/local/lib/liblthread.so.2 /usr/lib/libpthread.so
|
|
/sbin/ldconfig -m /usr/lib
|
|
|
|
If you do this, you can instead use:
|
|
|
|
-D_THREAD_SAFE -I/usr/local/include/pthread/linuxthreads -lpthread -llgcc_r
|
|
|
|
Another option is to create a custom gcc specs file that tells the linker which
|
|
version of libgcc to use. To do this, create a file with the following in it:
|
|
|
|
--- (/foo/specs) cut here ---
|
|
*libgcc:
|
|
/usr/local/lib/liblgcc_r.a
|
|
--- (/foo/specs) cut here ---
|
|
|
|
Then use the following command line options:
|
|
|
|
-B/foo/ -D_THREAD_SAFE -I/usr/local/include/pthread/linuxthreads -llthread
|
|
|
|
or if you created symlinks:
|
|
|
|
-B/foo/ -D_THREAD_SAFE -I/usr/local/include/pthread/linuxthreads -lpthread
|
|
|
|
2) If you plan on having lots of threads, check the sysctl value of
|
|
kern.maxproc. Each kernel thread counts against maxproc. You can increase
|
|
maxproc by changing the MAXUSERS value in your kernel config file. maxproc is
|
|
set at 20 + 16 * MAXUSERS.
|
|
|
|
3) Be aware of the following libc issues:
|
|
|
|
a) Not all libc calls are thread safe. In particular gmtime, localtime, etc
|
|
are not thread safe. In general, where the pthreads spec calls for "_r"
|
|
functions, these are either not provided, or if provided are not thread safe
|
|
(in most cases) and the related libc calls are not thread safe. This differs
|
|
somewhat from the FreeBSD libc_r library, where some, but not all, of these
|
|
functions are both thread safe and have "_r" versions.
|
|
|
|
b) Not all of the libc calls that are supposed to be cancellation points are
|
|
implemented as such. While linux threads has the cancel functions
|
|
implemented, deferred cancellation will not work as required by POSIX
|
|
1003.1c-1995, since the co-operation needed from libc is not complete.
|
|
|
|
c) The mutex wrapper functions only provide standard linuxthreads mutexes
|
|
(i.e. non-recursive mutexes). This might lead to deadlocks if libc
|
|
depends on recursive mutexes.
|
|
|
|
4) Be aware of the following libgcc issue:
|
|
|
|
FreeBSD 4.* (gcc 2.*):
|
|
|
|
__register_frame_info() and __get_eh_info() from libgcc.a are linked
|
|
into shared libraries that use exceptions, e.g. libstdc++. Those
|
|
functions are not compatible with linuxthreads due to pthread_mutex_t
|
|
and pthread_once_t having different sizes and static initializers.
|
|
Linking the shared linuxthreads library before any such library causes
|
|
the liblgcc_r.a version of those functions to be used.
|
|
|
|
FreeBSD 5.* (gcc 3.*):
|
|
|
|
__register_frame_info() and __frame_state_for() from libgcc.a are
|
|
linked into shared libraries that use exceptions, e.g. libstdc++.
|
|
Those functions are not compatible with linuxthreads due to
|
|
pthread_mutex_t and pthread_once_t having different sizes and static
|
|
initializers. Linking the shared linuxthreads library before any such
|
|
library causes the liblgcc_r.a version of those functions to be used.
|
|
Use liblstdc++ and liblsupc++.
|
|
|
|
Experimental wrapper support:
|
|
|
|
If the linuxthreads library has been compiled with
|
|
LINUXTHREADS_WRAP_API defined in the ports makefile then
|
|
the API functions are internally prefixed with linuxthreads_
|
|
to avoid conflict with native threads. Weak symbols without
|
|
that prefix points to the wrapper functions (internally
|
|
prefixed by _) that makes the linuxthreads functions available
|
|
with the native threads API. Applications including the
|
|
linuxthreads version of pthread.h will try to call the
|
|
prefixed methods (e.g. linuxthreads_pthread_create) while
|
|
applications including the native pthread.h will use the
|
|
wrapper functions. This allows for some level of coexistence
|
|
of libraries compiled with linuxthreads header file and
|
|
libraries compiled with native threads header files as long
|
|
as none of the pthread data types leaks out as function arguments
|
|
or structure members.
|
|
|
|
5) Exit handling is broken.
|
|
|
|
If the linuxthreads library has been compiled with
|
|
LINUXTHREADS_DETECT_UNSAFE_EXIT defined in the ports makefile then
|
|
the library tries to avoid further calls to functions registered
|
|
with atexit if not called from the main thread or if other threads
|
|
were active. Since this implicitly indicates a failure to do
|
|
proper cleanup, the exit code is then changed to 1.
|
|
|
|
If the linuxthreads library has been compiled without
|
|
LINUXTHREADS_DETECT_UNSAFE_EXIT, then calls to exit() has a
|
|
slightly higher probability of crashing or hanging the program when
|
|
other threads are active. If another thread than the main thread
|
|
performs the exit call, the exit code will appear to be 0.
|
|
|
|
If multiple threads calls exit then the application will likely
|
|
crash.
|
|
|
|
If other threads has been joined by the main thread before it calls
|
|
exit then exit handling should be fairly safe and the correct exit
|
|
code can be detected by the parent process.
|
|
|
|
6) If the rate of sched_yield() calls is very high (due to
|
|
malloc / spinlock interaction) then
|
|
LINUXTHREADS_NO_POSIX_PRIORITY_SCHEDULING can be defined when
|
|
compiling the linuxthreads library. This has the same effect
|
|
as if the kernel was compiled without the _KPOSIX_PRIORITY_SCHEDULING
|
|
option, but limited to the linuxthread library.
|
|
|
|
7) libraries using SIGUSR2 or SIGUSR1 will conflict with linuxthreads.
|
|
SIGUSR1 is hardcoded in the FreeBSD kernel (cf. RFLINUXTHPN flag
|
|
passed to rfork()), but the linuxthreads library can be changed to use
|
|
another signal instead of SIGUSR2 by defining LINUXTHREADS_ALT_RESTARTSIG
|
|
to the alternate signal number (e.g. 32).
|
|
|
|
8) By default, the maximum thread stack size is 2 MB, and the maximum
|
|
number of threads is 1024. Layout of stacks are based on the
|
|
maximum thread stack size. This means that 2 GB of the address space
|
|
can be used by thread stacks, limiting what is left for other
|
|
purposes (text, data, bss, heap, mmap). To shrink the address range
|
|
used for thread stacks, the maximum thread stack size can be changed
|
|
by defining LINUXTHREADS_MAX_STACK_SIZE to a suitable value, e.g.
|
|
1048576. The maximum number of threads can be changed by defining
|
|
LINUXTHREADS_MAX_THREADS to a suitable value, e.g. 2048.
|
|
The product of the maximum thread stack size and the maximum number
|
|
of threads should not exceed 2 GB. The maximum stack size must be
|
|
a power of 2.
|
|
|
|
9) The complete FreeBSD source code matching the installed userland
|
|
must be installed in /usr/src before building linuxthreads.
|