Reword the "threads still running" cleanup message.

[perl5.git] / README.threads

diff --git a/README.threads b/README.threads
index b02e607..9cd0dbc 100644 (file)
--- a/README.threads
+++ b/README.threads
@@ -1,7 +1,33 @@
-NOTE
+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 really want the older support for threads described below,
+it is enabled with:
+
+    sh Configure -Dusethreads -Duse5005threads
+
+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.)
+
+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.
 
-Threading is a highly experimental feature.  There are still a 
-few race conditions that show up under high contention on SMP
+---------------------------------------------------------------------------
+
+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.
 
@@ -11,7 +37,7 @@ Building
 
 If your system is in the following list you should be able to just:
 
-    ./Configure -Dusethreads -des
+    ./Configure -Dusethreads -Duse5005threads -des
     make
 
 and ignore the rest of this "Building" section.  If not, continue
@@ -38,7 +64,7 @@ from the "Problems" section.
 
        * OpenBSD
 
-       * NeXTstep, OpenStep (Rhapsody?)
+       * NeXTstep, OpenStep
 
        * OS/2
 
@@ -58,7 +84,7 @@ subdirectory.
 On platforms that use Configure to build perl, omit the -d from your
 ./Configure arguments. For example, use:
 
-    ./Configure -Dusethreads
+    ./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,
@@ -85,7 +111,7 @@ For Digital Unix 4.x:
     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
@@ -132,7 +158,7 @@ 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
+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.
 
@@ -168,8 +194,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
@@ -204,7 +230,7 @@ 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__)
+    #if defined(DEBUGGING) && defined(USE_5005THREADS) && defined(__linux__)
         DEBUG_S(signal(SIGSEGV, (void(*)(int))catch_sigsegv););
     #endif
 
@@ -252,7 +278,7 @@ 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
+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).