Strengthen cautions about locale use with threads

This comes from our increased understanding of their perils, given
ticket #127708

3 files changed, 35 insertions, 5 deletions

diff --git a/ext/POSIX/lib/POSIX.pod b/ext/POSIX/lib/POSIX.pod
index a31518fa50..1d263a7bc4 100644
--- a/ext/POSIX/lib/POSIX.pod
+++ b/ext/POSIX/lib/POSIX.pod
@@ -1405,6 +1405,13 @@ see L<perlfunc/eval>.
 
 =item C<setlocale>
 
+WARNING!  Do NOT use this function in a L<thread|threads>.  The locale
+will change in all other threads at the same time, and should your
+thread get paused by the operating system, and another started, that
+thread will not have the locale it is expecting.  On some platforms,
+there can be a race leading to segfaults if two threads call this
+function nearly simultaneously.
+
 Modifies and queries the program's underlying locale.  Users of this
 function should read L<perllocale>, whch provides a comprehensive
 discussion of Perl locale handling, knowledge of which is necessary to
diff --git a/lib/locale.pm b/lib/locale.pm
index e2317ca871..02e4bb2434 100644
--- a/lib/locale.pm
+++ b/lib/locale.pm
@@ -1,6 +1,6 @@
 package locale;
 
-our $VERSION = '1.08';
+our $VERSION = '1.09';
 use Config;
 
 $Carp::Internal{ (__PACKAGE__) } = 1;
@@ -9,6 +9,17 @@ $Carp::Internal{ (__PACKAGE__) } = 1;
 
 locale - Perl pragma to use or avoid POSIX locales for built-in operations
 
+=head1 WARNING
+
+DO NOT USE this pragma in scripts that have multiple
+L<threads|threads> active.  The locale is not local to a single thread.
+Another thread may change the locale at any time, which could cause at a
+minimum that a given thread is operating in a locale it isn't expecting
+to be in.  On some platforms, segfaults can also occur.  The locale
+change need not be explicit; some operations cause perl to change the
+locale itself.  You are vulnerable simply by having done a C<"use
+locale">.
+
 =head1 SYNOPSIS
 
     @x = sort @y;      # Native-platform/Unicode code point sort order
diff --git a/pod/perllocale.pod b/pod/perllocale.pod
index 0ab6452a6a..e1f34f1e72 100644
--- a/pod/perllocale.pod
+++ b/pod/perllocale.pod
@@ -164,6 +164,15 @@ L<The setlocale function>.
 
 =head2 The C<"use locale"> pragma
 
+WARNING!  Do NOT use this pragma in scripts that have multiple
+L<threads|threads> active.  The locale is not local to a single thread.
+Another thread may change the locale at any time, which could cause at a
+minimum that a given thread is operating in a locale it isn't expecting
+to be in.  On some platforms, segfaults can also occur.  The locale
+change need not be explicit; some operations cause perl to change the
+locale itself.  You are vulnerable simply by having done a C<"use
+locale">.
+
 By default, Perl itself (outside the L<POSIX> module)
 ignores the current locale.  The S<C<use locale>>
 pragma tells Perl to use the current locale for some operations.
@@ -389,6 +398,13 @@ this, as described in L</Unicode and UTF-8>.
 
 =head2 The setlocale function
 
+WARNING!  Do NOT use this function in a L<thread|threads>.  The locale
+will change in all other threads at the same time, and should your
+thread get paused by the operating system, and another started, that
+thread will not have the locale it is expecting.  On some platforms,
+there can be a race leading to segfaults if two threads call this
+function nearly simultaneously.
+
 You can switch locales as often as you wish at run time with the
 C<POSIX::setlocale()> function:
 
@@ -417,10 +433,6 @@ C<POSIX::setlocale()> function:
         # restore the old locale
         setlocale(LC_CTYPE, $old_locale);
 
-This simultaneously affects all threads of the program, so it may be
-problematic to use locales in threaded applications except where there
-is a single locale applicable to all threads.
-
 The first argument of C<setlocale()> gives the B<category>, the second the
 B<locale>.  The category tells in what aspect of data processing you
 want to apply locale-specific rules.  Category names are discussed in