Add PERL_REENTRANT for XS modules

This allows them to get the reentrant versions of libc functions
automatically.  Previously if they wanted to do this, they had to
declare themselves (shudder) as PERL_CORE or PERL_EXT.

4 files changed, 29 insertions, 10 deletions

diff --git a/dist/ExtUtils-ParseXS/lib/perlxs.pod b/dist/ExtUtils-ParseXS/lib/perlxs.pod
index e887d33ca7..6b21d966a9 100644
--- a/dist/ExtUtils-ParseXS/lib/perlxs.pod
+++ b/dist/ExtUtils-ParseXS/lib/perlxs.pod
@@ -2051,11 +2051,18 @@ you need to do is to instantiate a Perl interpreter.
 
 This wrapping happens always when compiling Perl core source
 (PERL_CORE is defined) or the Perl core extensions (PERL_EXT is
-defined).  When compiling XS code outside of Perl core the wrapping
-does not take place.  Note, however, that intermixing the _r-forms
-(as Perl compiled for multithreaded operation will do) and the _r-less
-forms is neither well-defined (inconsistent results, data corruption,
-or even crashes become more likely), nor is it very portable.
+defined).  When compiling XS code outside of the Perl core, the wrapping
+does not take place before Perl 5.28.  Starting in that release you can
+
+ #define PERL_REENTRANT
+
+in your code to enable the wrapping.  It is advisable to do so if you
+are using such functions, as intermixing the C<_r>-forms (as Perl compiled
+for multithreaded operation will do) and the C<_r>-less forms is neither
+well-defined (inconsistent results, data corruption, or even crashes
+become more likely), nor is it very portable.  Unfortunately, not all
+systems have all the C<_r> forms, but using this C<#define> gives you
+whatever protection that Perl is aware is available on each system.
 
 =head1 EXAMPLES
 
diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index 7ef8c7fff8..c9dd65f83f 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -373,13 +373,25 @@ XXX Changes which affect the interface available to C<XS> code go here.  Other
 significant internal changes for future core maintainers should be noted as
 well.
 
-[ List each change as an =item entry ]
-
 =over 4
 
 =item *
 
-XXX
+XS modules can now automatically get reentrant versions of system
+functions on threaded perls.
+
+By saying
+
+ #define PERL_REENTRANT
+
+near the beginning of an C<XS> file, it will be compiled so that
+whatever reentrant functions perl knows about on that system will
+automatically and invisibly be used instead of the plain, non-reentrant
+versions.  For example, if you write C<getpwnam()> in your code, on a
+system that has C<pwnam_r()> all calls to the former will be translated
+invisibly into the latter.  This does not happen except on threaded
+perls, as they aren't needed otherwise.  Be aware that which functions
+have reentrant versions varies from system to system.
 
 =back
 
diff --git a/reentr.h b/reentr.h
index b220b1ee53..6d085aa7dd 100644
--- a/reentr.h
+++ b/reentr.h
@@ -23,7 +23,7 @@
  */
 
 #ifndef PERL_REENTR_API
-# if defined(PERL_CORE) || defined(PERL_EXT)
+# if defined(PERL_CORE) || defined(PERL_EXT) || defined(PERL_REENTRANT)
 #  define PERL_REENTR_API 1
 # else
 #  define PERL_REENTR_API 0
diff --git a/regen/reentr.pl b/regen/reentr.pl
index 397f8ed091..0dbb79b774 100644
--- a/regen/reentr.pl
+++ b/regen/reentr.pl
@@ -73,7 +73,7 @@ print $h <<EOF;
  */
 
 #ifndef PERL_REENTR_API
-# if defined(PERL_CORE) || defined(PERL_EXT)
+# if defined(PERL_CORE) || defined(PERL_EXT) || defined(PERL_REENTRANT)
 #  define PERL_REENTR_API 1
 # else
 #  define PERL_REENTR_API 0