adjust notes on use5005threads

p4raw-id: //depot/perl@4964

3 files changed, 26 insertions, 9 deletions

diff --git a/Configure b/Configure
index 6a26b3330f..8fdb445218 100755
--- a/Configure
+++ b/Configure
@@ -2652,7 +2652,7 @@ esac'
 
 cat <<EOM
 
-Perl can be built to take advantage of threads, on some systems.
+Perl can be built to take advantage of threads on some systems.
 To do so, Configure must be run with -Dusethreads.
 
 Note that threading is a highly experimental feature, and
@@ -2683,6 +2683,10 @@ the 5.005 version (5005threads) and an interpreter-based version
 (ithreads) that has one interpreter per thread.  Both are very 
 experimental.  This arrangement exists to help developers work out
 which one is better.
+
+If you're a casual user, you probably don't want interpreter-threads
+at this time.  There doesn't yet exist a way to create threads from
+within Perl in this model, i.e., "use Thread;" will NOT work.
 EOM
 	: Default to ithreads unless overridden on command line or with
 	: old config.sh
diff --git a/INSTALL b/INSTALL
index 8da9b3e6fb..d38778305c 100644
--- a/INSTALL
+++ b/INSTALL
@@ -917,7 +917,7 @@ to turn off each extension:
     SDBM_File		(Always included by default)
     Opcode		useopcode
     Socket		d_socket
-    Threads		usethreads
+    Threads		use5005threads
     attrs		(Always included by default)
 
 Thus to skip the NDBM_File extension, you can use
diff --git a/README.threads b/README.threads
index b02e607d2b..1f5f7ea070 100644
--- a/README.threads
+++ b/README.threads
@@ -1,7 +1,20 @@
-NOTE
+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:
+
+    sh Configure -Dusethreads -Duse5005threads
+
+The rest of this document only applies to the use5005threads style of
+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 +24,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
@@ -58,7 +71,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,
@@ -168,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