[perl #121223] encourage use of PERL_NO_GET_CONTEXT

2 files changed, 24 insertions, 1 deletions

diff --git a/dist/ExtUtils-ParseXS/lib/perlxs.pod b/dist/ExtUtils-ParseXS/lib/perlxs.pod
index 12e2227ef4..122933b221 100644
--- a/dist/ExtUtils-ParseXS/lib/perlxs.pod
+++ b/dist/ExtUtils-ParseXS/lib/perlxs.pod
@@ -110,8 +110,12 @@ This XSUB will be invoked from Perl with the usage shown
 above.  Note that the first three #include statements, for
 C<EXTERN.h>, C<perl.h>, and C<XSUB.h>, will always be present at the
 beginning of an XS file.  This approach and others will be
-expanded later in this document.
+expanded later in this document.  A #define for C<PERL_NO_GET_CONTEXT>
+should be present to fetch the interpreter context more efficiently,
+see L<perlguts|perlguts/How multiple interpreters and concurrency are
+supported> for details.
 
+     #define PERL_NO_GET_CONTEXT
      #include "EXTERN.h"
      #include "perl.h"
      #include "XSUB.h"
@@ -1870,6 +1874,7 @@ the C<-g> (C<--global>) option with h2xs (see L<h2xs>).
 
 Below is an example module that makes use of the macros.
 
+    #define PERL_NO_GET_CONTEXT
     #include "EXTERN.h"
     #include "perl.h"
     #include "XSUB.h"
@@ -2050,6 +2055,7 @@ or even crashes become more likely), nor is it very portable.
 
 File C<RPC.xs>: Interface to some ONC+ RPC bind library functions.
 
+     #define PERL_NO_GET_CONTEXT
      #include "EXTERN.h"
      #include "perl.h"
      #include "XSUB.h"
diff --git a/dist/ExtUtils-ParseXS/lib/perlxstut.pod b/dist/ExtUtils-ParseXS/lib/perlxstut.pod
index 829e714b17..381622ebd0 100644
--- a/dist/ExtUtils-ParseXS/lib/perlxstut.pod
+++ b/dist/ExtUtils-ParseXS/lib/perlxstut.pod
@@ -79,6 +79,21 @@ instead of saying "C<make test>", you should say "C<make test_static>".
 On systems that cannot build dynamically-loadable libraries at all, simply
 saying "C<make test>" is sufficient.
 
+=head2 Threads and PERL_NO_GET_CONTEXT
+
+For threaded builds, perl requires the context pointer for the current
+thread, without C<PERL_NO_GET_CONTEXT>, perl will call a function to
+retrieve the context.
+
+For improved performance, include:
+
+  #define PERL_NO_GET_CONTEXT
+
+as shown below.
+
+For more details, see L<perlguts|perlguts/How multiple interpreters
+and concurrency are supported>.
+
 =head1 TUTORIAL
 
 Now let's go on with the show!
@@ -146,6 +161,7 @@ the extension.
 
 Finally, the Mytest.xs file should look something like this:
 
+    #define PERL_NO_GET_CONTEXT
     #include "EXTERN.h"
     #include "perl.h"
     #include "XSUB.h"
@@ -1227,6 +1243,7 @@ Suppose that for some strange reason we need a wrapper around the
 standard C library function C<fputs()>. This is all we need:
 
 	#define PERLIO_NOT_STDIO 0
+	#define PERL_NO_GET_CONTEXT
 	#include "EXTERN.h"
 	#include "perl.h"
 	#include "XSUB.h"