X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/ce637636a41b2fef0be4daa6d9d27b84e0907a74..884335e889637310f0c4472f3de03b5fcbc6d983:/README.threads diff --git a/README.threads b/README.threads index db54f7a..15d36de 100644 --- a/README.threads +++ b/README.threads @@ -1,62 +1,121 @@ -Building +NOTE: This documentation describes the style of threading that was +available in 5.005. Perl v5.6 also has the early beginnings of +interpreter-based threads support (which is what will be enabled by +default when you simply ask for -Dusethreads). However, be advised +that interpreter threads cannot as yet be created from the Perl level +yet. If you're looking to create threads from within Perl, chances +are you _don't_ want interpreter threads, but want the older support +for threads described below, enabled with: -If you want to build with multi-threading support and you are -running one of the following: - * 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 +The rest of this document only applies to the use5005threads style of +threads. +--------------------------------------------------------------------------- - * Solaris 2.x for recentish x (2.5 is OK) +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. - * 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. +--------------------------------------------------------------------------- + +Building -then you should be able to use - ./Configure -Dusethreads -Doptimize=-g -ders +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. - -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 + +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 + + * OS/2 + + * 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 (-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 +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 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: - Add -DUSE_THREADS -DDEBUGGING to ccflags - Add -DUSE_THREADS -DDEBUGGING to cppflags + (This should all be done automatically by the hint file). Add -lpthread to libs - Change optimize to -g 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 @@ -70,22 +129,31 @@ For IRIX: For IRIX 6.3 and 6.4 the pthreads should work out of the box. Thanks to Hannu Napari 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 -DUSE_THREADS -DNEED_PTHREAD_INIT -DDEBUGGING to ccflags and cppflags - Change optimize to -g + Add -DNEED_PTHREAD_INIT to ccflags and cppflags 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 previosuly 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 -Solaris qsort uses a hidden mutex for synchronisation. If you die() -while doing a sort() then the resulting longjmp() leaves the mutex -locked so you get a deadlock the next time you try to sort(). +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 @@ -113,8 +181,8 @@ has this fixed but the following patch can be applied to 0.5 for now: 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 @@ -130,32 +198,30 @@ Try running the main perl test suite too. There are known 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);); + DEBUG_S(signal(SIGSEGV, (void(*)(int))catch_sigsegv);); #endif +--------------------------------------------------------------------------- Background @@ -259,3 +325,12 @@ ZOMBIE ----------------------------> DEAD Malcolm Beattie mbeattie@sable.ox.ac.uk Last updated: 27 November 1997 + +Configure-related info updated 16 July 1998 by +Andy Dougherty + +Other minor updates 10 Feb 1999 by +Gurusamy Sarathy + +More platforms added 26 Jul 1999 by +Jarkko Hietaniemi