From 338b60d565f407821d90d94383579f89d4ba06cb Mon Sep 17 00:00:00 2001 From: Christian Walde Date: Sat, 1 Mar 2014 21:31:03 +0100 Subject: [PATCH] add discouragement warning to perl threads documentation 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 commit attempts to reduce the number of such incidences by putting a huge warning 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 hard to be +useful. Few people know how to use them correctly or will be able to provide +help. They mainly exist to provide C emulation on Windows and providing a +slightly useful imeplementation of threads is only a useful side effect. + +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 threads can +easily exhaust system memory. + +=item threads can crash easily if shared data isn't meticulously flagged + +Since there is no global lock each variable shared between threads needs 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 program 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 crashes. + +=back + +Because of the many limitations and potential for subtle bugs, B. + +In many situations one of the many asynchronous libraries on CPAN will 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 hard to be +useful. Few people know how to use them correctly or will be able to provide +help. They mainly exist to provide C emulation on Windows and providing a +slightly useful imeplementation of threads is only a useful side effect. + +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 threads can +easily exhaust system memory. + +=item threads can crash easily if shared data isn't meticulously flagged + +Since there is no global lock each variable shared between threads needs 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 program 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 crashes. + +=back + +Because of the many limitations and potential for subtle bugs, B. + +In many situations one of the many asynchronous libraries on CPAN will be a much +better solution. + =head1 DESCRIPTION This tutorial describes the use of Perl interpreter threads (sometimes -- 1.8.4.msysgit.0