Add PERL_REENTRANT for XS modules
authorKarl Williamson <khw@cpan.org>
Thu, 14 Dec 2017 02:07:04 +0000 (19:07 -0700)
committerKarl Williamson <khw@cpan.org>
Thu, 14 Dec 2017 02:14:33 +0000 (19:14 -0700)
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.

dist/ExtUtils-ParseXS/lib/perlxs.pod
pod/perldelta.pod
reentr.h
regen/reentr.pl

index e887d33..6b21d96 100644 (file)
@@ -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
 
index 7ef8c7f..c9dd65f 100644 (file)
@@ -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
 
index b220b1e..6d085aa 100644 (file)
--- 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
index 397f8ed..0dbb79b 100644 (file)
@@ -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