-Building
+NOTE: This documentation describes the style of threading that was
+available in Perl 5.005. Perl 5.6.0 introduced the early beginnings of
+interpreter-based threads support, also known as ithreads, and in Perl
+5.8.0 the interpeter threads became available from perl level through
+the threads and threads::shared modules (in Perl 5.6 ithreads are
+available only internally and to XS extension builders, and used
+by the Win32 port for emulating fork()). As of Perl 5.8.0, ithreads has
+become the standard threading model for Perl.
-If you want to build with multi-threading support and you are
-running one of the following:
+If you really want the older support for threads described below,
+it is enabled with:
- * Linux 2.x (with the LinuxThreads library installed: that's
- the linuxthreads and linuxthreads-devel RPMs for RedHat)
+ sh Configure -Dusethreads -Duse5005threads
- * Digital UNIX 4.x
+Be warned that the old 5.005 implementation of threads is known
+to be quite buggy, and unmaintained, which means that the bugs
+are there to stay. (We are not mean by not fixing the bugs:
+the bugs are just really, really, really hard to fix. Honest.)
- * Solaris 2.x for recentish x (2.5 is OK)
+The rest of this document only applies to the use5005threads style of
+threads, and the comments on what works on which platform are highly
+obsolete and preserved here for archaeology buffs only. The
+architecture specific hints files do all the necessary option
+tweaking automatically during Configure, both for the 5.005 threads
+and for the new interpreter threads.
- * IRIX 6.2 or newer. 6.2 will require a few os patches.
- IMPORTANT: Without patch 2401, a kernel bug in IRIX 6.2 will
- cause your machine to panic and crash when running threaded perl.
- IRIX 6.3 and up should be OK. See lower down for patch details.
+---------------------------------------------------------------------------
+
+Support for threading is still in the highly experimental stages. There
+are known race conditions that show up under high contention on SMP
+machines. Internal implementation is still subject to changes.
+It is not recommended for production use at this time.
-then you should be able to use
+---------------------------------------------------------------------------
- ./Configure -Dusethreads -des
+Building
+
+If your system is in the following list you should be able to just:
+
+ ./Configure -Dusethreads -Duse5005threads -des
make
-and ignore the rest of this "Building" section. If it doesn't
-work or you are using another platform which you believe supports
-POSIX.1c threads then read on. Additional information may be in
-a platform-specific "hints" file in the hints/ subdirectory.
+and ignore the rest of this "Building" section. If not, continue
+from the "Problems" section.
+
+ * Linux 2.* (with the LinuxThreads library installed:
+ that's the linuxthreads and linuxthreads-devel RPMs
+ for RedHat)
+
+ * Tru64 UNIX (formerly Digital UNIX formerly DEC OSF/1)
+ (see additional note below)
+
+ * Solaris 2.* for recentish x (2.5 is OK)
+
+ * IRIX 6.2 or newer. 6.2 will require a few OS patches.
+ IMPORTANT: Without patch 2401 (or its replacement),
+ a kernel bug in IRIX 6.2 will cause your machine to
+ panic and crash when running threaded perl.
+ IRIX 6.3 and up should be OK. See lower down for patch details.
+
+ * AIX 4.1.5 or newer.
+
+ * FreeBSD 2.2.8 or newer.
+
+ * OpenBSD
+
+ * NeXTstep, OpenStep
-Omit the -d from your ./Configure arguments. For example, use
+ * OS/2
- ./Configure -Dusethreads
+ * DOS DJGPP
+
+ * VM/ESA
+
+---------------------------------------------------------------------------
+
+Problems
+
+If the simple way doesn't work or you are using another platform which
+you believe supports POSIX.1c threads then read on. Additional
+information may be in a platform-specific "hints" file in the hints/
+subdirectory.
+
+On platforms that use Configure to build perl, omit the -d from your
+./Configure arguments. For example, use:
+
+ ./Configure -Dusethreads -Duse5005threads
When Configure prompts you for ccflags, insert any other arguments in
-there that your compiler needs to use POSIX threads. When Configure
-prompts you for linking flags, include any flags required for
-threading (usually nothing special is required here). Finally, when
-COnfigure prompts you for libraries, include any necessary libraries
-(e.g. -lpthread). Pay attention to the order of libraries. It is
-probably necessary to specify your threading library *before* your
-standard C library, e.g. it might be necessary to have -lpthread -lc,
-instead of -lc -lpthread.
+there that your compiler needs to use POSIX threads (-D_REENTRANT,
+-pthreads, -threads, -pthread, -thread, are good guesses). When
+Configure prompts you for linking flags, include any flags required
+for threading (usually nothing special is required here). Finally,
+when Configure prompts you for libraries, include any necessary
+libraries (e.g. -lpthread). Pay attention to the order of libraries.
+It is probably necessary to specify your threading library *before*
+your standard C library, e.g. it might be necessary to have -lpthread
+-lc, instead of -lc -lpthread. You may also need to use -lc_r instead
+of -lc.
Once you have specified all your compiler flags, you can have Configure
accept all the defaults for the remainder of the session by typing &-d
Add -lpthread -lc_r to lddlflags
For some reason, the extra includes for pthreads make Digital UNIX
- complain fatally about the sbrk() delcaration in perl's malloc.c
+ complain fatally about the sbrk() declaration in perl's malloc.c
so use the native malloc, e.g. sh Configure -Uusemymalloc, or
manually edit your config.sh as follows:
Change usemymalloc to n
Zap mallocobj and mallocsrc (foo='')
Change d_mymalloc to undef
+For Digital Unix 3.x (Formerly DEC OSF/1):
+ Add -DOLD_PTHREADS_API to ccflags
+ If compiling with the GNU cc compiler, remove -threads from ccflags
+
+ (The following should be done automatically if you call Configure
+ with the -Dusethreads option).
+ Add -lpthread -lmach -lc_r to libs (in the order specified).
+
For IRIX:
(This should all be done automatically by the hint file).
Add -lpthread to libs
For IRIX 6.3 and 6.4 the pthreads should work out of the box.
Thanks to Hannu Napari <Hannu.Napari@hut.fi> for the IRIX
pthreads patches information.
+
For AIX:
(This should all be done automatically by the hint file).
Change cc to xlc_r or cc_r.
Add -lc_r to libswanted
Change -lc in lddflags to be -lpthread -lc_r -lc
+For Win32:
+ See README.win32, and the notes at the beginning of win32/Makefile
+ or win32/makefile.mk.
+
Now you can do a
make
+When you succeed in compiling and testing ("make test" after your
+build) a threaded Perl in a platform previously unknown to support
+threaded perl, please let perlbug@perl.com know about your victory.
+Explain what you did in painful detail.
+
+---------------------------------------------------------------------------
O/S specific bugs
Building the Thread extension
The Thread extension is now part of the main perl distribution tree.
-If you did Configure -Dusethreads then it will have been added to
-the list of extensions automatically.
+If you did Configure -Dusethreads -Duse5005threads then it will have been
+added to the list of extensions automatically.
You can try some of the tests with
cd ext/Thread
failures for some of the DBM/DB extensions (if their underlying
libraries were not compiled to be thread-aware).
+---------------------------------------------------------------------------
Bugs
* FAKE_THREADS should produce a working perl but the Thread
-extension won't build with it yet.
-
-* There's a known memory leak (curstack isn't freed at the end
-of each thread because it causes refcount problems that I
-haven't tracked down yet) and there are very probably others too.
+extension won't build with it yet. (FAKE_THREADS has not been
+tested at all in recent times.)
* There may still be races where bugs show up under contention.
-* Need to document "lock", Thread.pm, Queue.pm, ...
-
+---------------------------------------------------------------------------
Debugging
-Use the -DL command-line option to turn on debugging of the
+Use the -DS command-line option to turn on debugging of the
multi-threading code. Under Linux, that also turns on a quick
hack I did to grab a bit of extra information from segfaults.
If you have a fancier gdb/threads setup than I do then you'll
have to delete the lines in perl.c which say
- #if defined(DEBUGGING) && defined(USE_THREADS) && defined(__linux__)
- DEBUG_L(signal(SIGSEGV, (void(*)(int))catch_sigsegv););
+ #if defined(DEBUGGING) && defined(USE_5005THREADS) && defined(__linux__)
+ DEBUG_S(signal(SIGSEGV, (void(*)(int))catch_sigsegv););
#endif
+---------------------------------------------------------------------------
Background
implementation of condition variables in certain porting situations.)
For POSIX threads, perl mutexes and condition variables correspond to
POSIX ones. For FAKE_THREADS, mutexes are stubs and condition variables
-are implmented as lists of waiting threads. For FAKE_THREADS, a thread
+are implemented as lists of waiting threads. For FAKE_THREADS, a thread
waits on a condition variable by removing itself from the runnable
list, calling SCHEDULE to change thr to the next appropriate
runnable thread and returning op (i.e. the new threads next op).
Configure-related info updated 16 July 1998 by
Andy Dougherty <doughera@lafayette.edu>
+
+Other minor updates 10 Feb 1999 by
+Gurusamy Sarathy
+
+More platforms added 26 Jul 1999 by
+Jarkko Hietaniemi
https://perl5.git.perl.org / perl5.git / blobdiff