I'd say this issue ("it's hard to use threads correctly") has at least four separate aspects worth considering in the context of Perl 5 and its documentation:
- Is concurrency appropriate? There are two basic motivations that can lead to use of concurrency constructs in programming: 1) because the domain naturally involves asynchronicity and 2) to speed things up. In the latter case, if the problem being tackled is really IO bound, turning to concurrency probably won't help.
It might be worth providing some simple rubrics in some Perl documentation to help folk figure out when concurrency likely will or won't be helpful.
- The Problem with Threads. For all but trivial problems, correctly using conventional low level concurrency constructs such as threads and locks is surprisingly difficult. This is true for all langs, even, say, erlang or clojure. It has nothing whatsoever to do with Perl.
It might be appropriate to warn most programmers away from use of low level constructs. Perhaps "Here Be Dragons And They WILL Burn You" goes too far and a link to "The Problem with Threads" or somesuch will suffice.
- Futures et al are the future. There are much simpler, safer, higher level ways to do concurrency. I haven't tried Paul Evans' Futures, but they look the part.
It think it is appropriate to encourage most programmers to use these higher level constructs.
- Perl 5 "threads" are very heavy. This sometimes introduces additional complexity.
I'd say this is worth mentioning, but it's perhaps the least important of the four points (though perhaps the most annoying to those expected to answer questions about them).
Finally, I'll note that the section Make the hard things possible in the P6 synopsis on Concurrency says:
Perl 6 should not hide the existence of OS-level threads, or fail to provide access to lower level concurrency control constructs. However, they should be clearly documented as not the way to solve the majority of problems.