From: Father Chrysostomos <sprout@cpan.org>
Date: Wed, 12 Oct 2011 06:02:41 +0000 (-0700)
Subject: Improve documentation of XS autoloading
X-Git-Tag: accepted/trunk/20130322.191538~2427
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=5b36e9450efc47317616775e6c3eb0daba56035c;p=platform%2Fupstream%2Fperl.git

Improve documentation of XS autoloading
---

diff --git a/cv.h b/cv.h
index ebc876a..baf7692 100644
--- a/cv.h
+++ b/cv.h
@@ -34,6 +34,9 @@ Returns the stash of the CV. A stash is the symbol table hash, containing
 the package-scoped variables in the package where the subroutine was defined.
 For more information, see L<perlguts>.
 
+This also has a special use with XS AUTOLOAD subs.
+See L<perlguts/Autoloading with XSUBs>.
+
 =cut
 */
 
diff --git a/pod/perlguts.pod b/pod/perlguts.pod
index 38ed3e1..97b9758 100644
--- a/pod/perlguts.pod
+++ b/pod/perlguts.pod
@@ -1498,6 +1498,26 @@ C<m(X)PUSH[iunp]> macros instead; see L</Putting a C value on Perl stack>.
 
 For more information, consult L<perlxs> and L<perlxstut>.
 
+=head2 Autoloading with XSUBs
+
+If an AUTOLOAD routine is an XSUB, as with Perl subroutines, Perl puts the
+fully-qualified name of the autoloaded subroutine in the $AUTOLOAD variable
+of the XSUB's package.
+
+But it also puts the same information in certain fields of the XSUB itself:
+
+    HV *stash           = CvSTASH(cv);
+    const char *subname = SvPVX(cv);
+    STRLEN name_length  = SvCUR(cv); /* in bytes */
+    U32 is_utf8         = SvUTF8(cv);
+    
+C<SvPVX(cv)> contains just the sub name itself, not including the package.
+
+B<Note>: Setting $AUTOLOAD stopped working in 5.6.1, which did not support
+XS AUTOLOAD subs at all.  Perl 5.8.0 introduced the use of fields in the
+XSUB itself.  Perl 5.16.0 restored the setting of $AUTOLOAD.  If you need
+to support 5.8-5.14, use the XSUB's fields.
+
 =head2 Calling Perl Routines from within C Programs
 
 There are four routines that can be used to call a Perl subroutine from
diff --git a/pod/perlsub.pod b/pod/perlsub.pod
index 6d034f1..9aae8ac 100644
--- a/pod/perlsub.pod
+++ b/pod/perlsub.pod
@@ -1432,8 +1432,8 @@ variable of the same package as the C<AUTOLOAD> routine.  The name
 is not passed as an ordinary argument because, er, well, just
 because, that's why.  (As an exception, a method call to a nonexistent
 C<import> or C<unimport> method is just skipped instead.  Also, if
-the AUTOLOAD subroutine is an XSUB, C<$AUTOLOAD> is not populated;
-see L<perlapi/SvPVX> for details.)
+the AUTOLOAD subroutine is an XSUB, there are other ways to retrieve the
+subroutine name.  See L<perlguts/Autoloading with XSUBs> for details.)
 
 
 Many C<AUTOLOAD> routines load in a definition for the requested
diff --git a/sv.h b/sv.h
index 46e53ac..72cd887 100644
--- a/sv.h
+++ b/sv.h
@@ -685,10 +685,8 @@ Only use when you are sure SvNOK is true. See also C<SvNV()>.
 Returns a pointer to the physical string in the SV.  The SV must contain a
 string.
 
-During autoloading, if the AUTOLOAD routine is an XSUB, C<SvPVX(cv)>
-returns the name of the subroutine for which AUTOLOAD was invoked.
-Likewise, C<SvCUR(cv)> returns the length, and C<SvUTF8(cv)> returns true
-if the name is in UTF8.
+This is also used to store the name of an autoloaded subroutine in an XS
+AUTOLOAD routine.  See L<perlguts/Autoloading with XSUBs>.
 
 =for apidoc Am|STRLEN|SvCUR|SV* sv
 Returns the length of the string which is in the SV.  See C<SvLEN>.