Building
If you want to build with multi-threading support and you are
-running Linux 2.x (with the LinuxThreads library installed:
-that's the linuxthreads and linuxthreads-devel RPMs for RedHat)
-or Digital UNIX 4.x or Solaris 2.x for recentish x (2.5 is OK)
+running one of the following:
+
+ * Linux 2.x (with the LinuxThreads library installed: that's
+ the linuxthreads and linuxthreads-devel RPMs for RedHat)
+
+ * Digital UNIX 4.x
+
+ * Solaris 2.x for recentish x (2.5 is OK)
+
+ * 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.
+
then you should be able to use
- ./Configure -Dusethreads -Doptimize=-g -ders
+
+ ./Configure -Dusethreads -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.
-
-Omit the -e from your ./Configure arguments. For example, use
- ./Configure -drs
-When it offers to let you change config.sh, do so. If you already
-have a config.sh then you can edit it and do
- ./Configure -S
-to propagate the required changes.
-In ccflags, insert -DUSE_THREADS (and probably -DDEBUGGING since
-that's what I've been building with). Also insert any other
-arguments in there that your compiler needs to use POSIX threads.
-Change optimize to -g to give you better debugging information.
-Include any necessary explicit libraries in libs and change
-ldflags if you need any linker flags instead or as well.
-
-More explicitly, for Linux (when using the standard kernel-threads
-based LinuxThreads library):
- Add -DUSE_THREADS -D_REENTRANT -DDEBUGGING to ccflags and cppflags
- Add -lpthread to libs
- Change optimize to -g
+POSIX.1c threads then read on. Additional information may be in
+a platform-specific "hints" file in the hints/ subdirectory.
+
+Omit the -d from your ./Configure arguments. For example, use
+
+ ./Configure -Dusethreads
+
+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.
+
+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
+at any Configure prompt.
+
+Some additional notes (some of these may be obsolete now, other items
+may be handled automatically):
+
For Digital Unix 4.x:
- Add -pthread -DUSE_THREADS -DDEBUGGING to ccflags
- Add -DUSE_THREADS -DDEBUGGING to cppflags
+ Add -pthread to ccflags
Add -pthread to ldflags
- Change optimize to -g
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
- so use the native malloc as follows:
- Change usemymalloc to n
- Zap mallocobj and mallocsrc (foo='')
- Change d_mymalloc to undef
-For Solaris, do the same as for Linux above.
+ 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 IRIX:
+ (This should all be done automatically by the hint file).
+ Add -lpthread to libs
+ For IRIX 6.2, you have to have the following patches installed:
+ 1404 Irix 6.2 Posix 1003.1b man pages
+ 1645 IRIX 6.2 & 6.3 POSIX header file updates
+ 2000 Irix 6.2 Posix 1003.1b support modules
+ 2254 Pthread library fixes
+ 2401 6.2 all platform kernel rollup
+ 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.
+
+ 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 -DNEED_PTHREAD_INIT to ccflags and cppflags
+ Add -lc_r to libswanted
+ Change -lc in lddflags to be -lpthread -lc_r -lc
Now you can do a
make
-Building the Thread extension
+O/S specific bugs
+
+Irix 6.2: See the Irix warning above.
+
+LinuxThreads 0.5 has a bug which can cause file descriptor 0 to be
+closed after a fork() leading to many strange symptoms. Version 0.6
+has this fixed but the following patch can be applied to 0.5 for now:
+
+----------------------------- cut here -----------------------------
+--- linuxthreads-0.5/pthread.c.ORI Mon Oct 6 13:55:50 1997
++++ linuxthreads-0.5/pthread.c Mon Oct 6 13:57:24 1997
+@@ -312,8 +312,10 @@
+ free(pthread_manager_thread_bos);
+ pthread_manager_thread_bos = pthread_manager_thread_tos = NULL;
+ /* Close the two ends of the pipe */
+- close(pthread_manager_request);
+- close(pthread_manager_reader);
++ if (pthread_manager_request >= 0) {
++ close(pthread_manager_request);
++ close(pthread_manager_reader);
++ }
+ pthread_manager_request = pthread_manager_reader = -1;
+ /* Update the pid of the main thread */
+ self->p_pid = getpid();
+----------------------------- cut here -----------------------------
-Build it away from the perl tree in the usual way. Set your PATH
-environment variable to have your perl build directory first and
-set PERL5LIB to be /your/perl/build/directory/lib (without those,
-I had problems where the config information from the ordinary perl
-on the system would end up in the Makefile). Then
- perl Makefile.PL PERL_SRC=/your/perl/build/directory
- make
-Then you can try some of the tests with
- perl -Mblib create.t
- perl -Mblib join.t
- perl -Mblib lock.t
- perl -Mblib unsync.t
- perl -Mblib unsync2.t
- perl -Mblib unsync3.t
- perl -Mblib io.t
- perl -Mblib queue.t
+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.
+
+You can try some of the tests with
+ cd ext/Thread
+ perl create.t
+ perl join.t
+ perl lock.t
+ perl io.t
+etc.
The io one leaves a thread reading from the keyboard on stdin so
as the ping messages appear you can type lines and see them echoed.
Try running the main perl test suite too. There are known
-failures for po/misc test 45 (tries to do local(@_) but @_ is
-now lexical) and some tests involving backticks/system/fork
-may or may not work. Under Linux, many tests may appear to fail
-when run under the test harness but work fine when invoked
-manually.
+failures for some of the DBM/DB extensions (if their underlying
+libraries were not compiled to be thread-aware).
Bugs
-* cond.t hasn't been redone since condition variable changed.
-
* FAKE_THREADS should produce a working perl but the Thread
extension won't build with it yet.
of each thread because it causes refcount problems that I
haven't tracked down yet) and there are very probably others too.
-* There are still races where bugs show up under contention.
+* There may still be races where bugs show up under contention.
* Need to document "lock", Thread.pm, Queue.pm, ...
-* Plenty of others
-
Debugging
Some old globals (e.g. stack_sp, op) and some old per-interpreter
variables (e.g. tmps_stack, cxstack) move into struct thread.
-All fields of struct thread (apart from a few only applicable to
-FAKE_THREADS) are of the form Tfoo. For example, stack_sp becomes
+All fields of struct thread which derived from original perl
+variables have names of the form Tfoo. For example, stack_sp becomes
the field Tstack_sp of struct thread. For those fields which moved
from original perl, thread.h does
#define foo (thr->Tfoo)
Mutexes and condition variables
The API is via macros MUTEX_{INIT,LOCK,UNLOCK,DESTROY} and
-COND_{INIT,WAIT,SIGNAL,BROADCAST,DESTROY}. 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
+COND_{INIT,WAIT,SIGNAL,BROADCAST,DESTROY}.
+
+A mutex is only required to be a simple, fast mutex (e.g. it does not
+have to be recursive). It is only ever held across very short pieces
+of code. Condition variables are only ever signalled/broadcast while
+their associated mutex is held. (This constraint simplifies the
+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
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).
condition variables list into the run queue. Note that a mutex
must *not* be held while returning from a PP function.
-Perl locks are a condpair_t structure (a triple of a mutex, a
-condtion variable and an owner thread field) attached by 'm'
-magic to any SV. pp_lock locks such an object by waiting on the
-condition variable until the owner field is zero and then setting
-the owner field to its own thread pointer. The lock is recursive
-so if the owner field already matches the current thread then
-pp_lock returns straight away. If the owner field has to be filled
-in then unlock_condpair is queued as an end-of-block destructor and
-that function zeroes out the owner field, releasing the lock.
+Perl locks and condition variables are both implemented as a
+condpair_t structure, containing a mutex, an "owner" condition
+variable, an owner thread field and another condition variable).
+The structure is attached by 'm' magic to any SV. pp_lock locks
+such an object by waiting on the ownercond condition variable until
+the owner field is zero and then setting the owner field to its own
+thread pointer. The lock is semantically recursive so if the owner
+field already matches the current thread then pp_lock returns
+straight away. If the owner field has to be filled in then
+unlock_condpair is queued as an end-of-block destructor and
+that function zeroes out the owner field and signals the ownercond
+condition variable, thus waking up any other thread that wants to
+lock it. When used as a condition variable, the condpair is locked
+(involving the above wait-for-ownership and setting the owner field)
+and the spare condition variable field is used for waiting on.
+
+
+Thread states
+
+
+ $t->join
+R_JOINABLE ---------------------> R_JOINED >----\
+ | \ pthread_join(t) | ^ |
+ | \ | | join | pthread_join
+ | \ | | |
+ | \ | \------/
+ | \ |
+ | \ |
+ | $t->detach\ pthread_detach |
+ | _\| |
+ends| R_DETACHED ends | unlink
+ | \ |
+ | ends \ unlink |
+ | \ |
+ | \ |
+ | \ |
+ | \ |
+ | \ |
+ V join detach _\| V
+ZOMBIE ----------------------------> DEAD
+ pthread_join pthread_detach
+ and unlink and unlink
+
Malcolm Beattie
mbeattie@sable.ox.ac.uk
-2 October 1997
+Last updated: 27 November 1997
+
+Configure-related info updated 16 July 1998 by
+Andy Dougherty <doughera@lafayette.edu>
https://perl5.git.perl.org / perl5.git / blobdiff