From 338b60d565f407821d90d94383579f89d4ba06cb Mon Sep 17 00:00:00 2001
From: Christian Walde <walde.christian@googlemail.com>
Date: Sat, 1 Mar 2014 21:31:03 +0100
Subject: [PATCH] add discouragement warning to perl threads documentat
+ion

The common reactions to someone asking for help with threads even in #
+p5p
being: "You're doing it wrong!" or "You have brain damage!" This commi
+t
attempts to reduce the number of such incidences by putting a huge war
+ning
on the threads documentation that should discourage all but the most
determined.
---
 dist/threads/lib/threads.pm | 43 ++++++++++++++++++++++++++++++++++++
++++++++
 pod/perlthrtut.pod          | 43 ++++++++++++++++++++++++++++++++++++
++++++++
 2 files changed, 86 insertions(+)

diff --git a/dist/threads/lib/threads.pm b/dist/threads/lib/threads.pm
index b8ee229..559576b 100644
--- a/dist/threads/lib/threads.pm
+++ b/dist/threads/lib/threads.pm
@@ -136,6 +136,49 @@ threads - Perl interpreter-based threads
 
 This document describes threads version 1.92
 
+=head1 WARNING
+
+Threads are implemented in a way that make them easy to misuse and ha
+rd to be
+useful. Few people know how to use them correctly or will be able to 
+provide
+help. They mainly exist to provide C<fork> emulation on Windows and p
+roviding a
+slightly useful imeplementation of threads is only a useful side effe
+ct.
+
+The main issues you will encounter with them are these:
+
+=over
+
+=item starting a new thread is very slow
+
+Whenever a new thread is started it is created by copying the entire 
+parent
+thread, which takes some time and thus makes it impossible to spin up
+ a large
+number of threads on demand in a speedy manner.
+
+=item starting a new thread will use a lot of ram
+
+Due to the mentioned copying each thread will use up exactly as much 
+memory as
+the parent thread and thus spinning up even a moderate amount of thre
+ads can
+easily exhaust system memory.
+
+=item threads can crash easily if shared data isn't meticulously flag
+ged
+
+Since there is no global lock each variable shared between threads ne
+eds to be
+flagged carefully, including each element of a complex data structure
+, otherwise
+hard to debug crashes are guaranteed.
+
+=item many modules are not thread-safe and will cause crashes
+
+Due to the previous issue, any module that is used in a threaded prog
+ram must
+also take care. Especially XS modules are a danger because they need 
+to be made
+thread-safe on the C layer as well. However few do this and cause cra
+shes.
+
+=back
+
+Because of the many limitations and potential for subtle bugs, B<use 
+of threads
+is discouraged>.
+
+In many situations one of the many asynchronous libraries on CPAN wil
+l be a much
+better solution.
+
 =head1 SYNOPSIS
 
     use threads ('yield',
diff --git a/pod/perlthrtut.pod b/pod/perlthrtut.pod
index e885bb2..a3354af 100644
--- a/pod/perlthrtut.pod
+++ b/pod/perlthrtut.pod
@@ -4,6 +4,49 @@
 
 perlthrtut - Tutorial on threads in Perl
 
+=head1 WARNING
+
+Threads are implemented in a way that make them easy to misuse and ha
+rd to be
+useful. Few people know how to use them correctly or will be able to 
+provide
+help. They mainly exist to provide C<fork> emulation on Windows and p
+roviding a
+slightly useful imeplementation of threads is only a useful side effe
+ct.
+
+The main issues you will encounter with them are these:
+
+=over
+
+=item starting a new thread is very slow
+
+Whenever a new thread is started it is created by copying the entire 
+parent
+thread, which takes some time and thus makes it impossible to spin up
+ a large
+number of threads on demand in a speedy manner.
+
+=item starting a new thread will use a lot of ram
+
+Due to the mentioned copying each thread will use up exactly as much 
+memory as
+the parent thread and thus spinning up even a moderate amount of thre
+ads can
+easily exhaust system memory.
+
+=item threads can crash easily if shared data isn't meticulously flag
+ged
+
+Since there is no global lock each variable shared between threads ne
+eds to be
+flagged carefully, including each element of a complex data structure
+, otherwise
+hard to debug crashes are guaranteed.
+
+=item many modules are not thread-safe and will cause crashes
+
+Due to the previous issue, any module that is used in a threaded prog
+ram must
+also take care. Especially XS modules are a danger because they need 
+to be made
+thread-safe on the C layer as well. However few do this and cause cra
+shes.
+
+=back
+
+Because of the many limitations and potential for subtle bugs, B<use 
+of threads
+is discouraged>.
+
+In many situations one of the many asynchronous libraries on CPAN wil
+l be a much
+better solution.
+
 =head1 DESCRIPTION
 
 This tutorial describes the use of Perl interpreter threads (sometime
+s
-- 
1.8.4.msysgit.0
[download]