Integrate:

[ 22286]
Subject: [PATCH] Correct some prototypes in perlapi.pod
Message-ID: <40238C15.2090200@uk.radan.com>

[ 22330]
1. Add section to perlxs.pod describing that the refcount of AVs/HVs
   returned from XSUBs through RETVAL isn't decremented as it is for
   SVs. This causes those XSUBs to leak memory and cannot be fixed
   without breaking existing CPAN modules that work around this bug.

2. Fix a memory leak of that kind in POSIX::localconv.

[ 22338]
Add base.pm and fields.pm to the maintainer list.
Remove a duplicate file from this list.
p4raw-link: @22338 on //depot/perl: adf7fd8780435ef21631ce9befe56b5adf2801fc
p4raw-link: @22330 on //depot/perl: c4e79b56de248a67c4a29293bd16f39465dde417
p4raw-link: @22286 on //depot/perl: 12fa07dffe20be11e9d779f98ee2eac72af90827

p4raw-id: //depot/maint-5.8/perl@22389
p4raw-integrated: from //depot/perl@22388 'copy in' pod/perlxs.pod
	(@19699..) ext/POSIX/POSIX.xs (@21993..) Porting/Maintainers.pl
	(@22244..)
p4raw-integrated: from //depot/perl@22286 'merge in' sv.h (@22163..)
	pod/perlapi.pod (@22264..)

diff --git a/Porting/Maintainers.pl b/Porting/Maintainers.pl
index ac0848c..7bda1ef 100644 (file)
--- a/Porting/Maintainers.pl
+++ b/Porting/Maintainers.pl
@@ -81,6 +81,13 @@ package Maintainers;
                'CPAN'          => 0,
                },
 
+       'base' =>
+               {
+               'MAINTAINER'    => 'mschwern',
+               'FILES'         => q[lib/base.pm lib/fields.pm lib/base],
+               'CPAN'          => 1,
+               },
+
        'bignum' =>
                {
                'MAINTAINER'    => 'tels',
@@ -140,7 +147,7 @@ package Maintainers;
        'Digest' =>
                {
                'MAINTAINER'    => 'gaas',
-               'FILES'         => q[lib/Digest.pm lib/Digest/base.pm lib/Digest],
+               'FILES'         => q[lib/Digest.pm lib/Digest],
                'CPAN'          => 1,
                },
 

diff --git a/ext/POSIX/POSIX.xs b/ext/POSIX/POSIX.xs
index deefbd1..8a0188d 100644 (file)
--- a/ext/POSIX/POSIX.xs
+++ b/ext/POSIX/POSIX.xs
@@ -1013,6 +1013,7 @@ localeconv()
 #ifdef HAS_LOCALECONV
        struct lconv *lcbuf;
        RETVAL = newHV();
+       sv_2mortal((SV*)RETVAL);
        if ((lcbuf = localeconv())) {
            /* the strings */
            if (lcbuf->decimal_point && *lcbuf->decimal_point)

diff --git a/pod/perlapi.pod b/pod/perlapi.pod
index 8d86f85..a013c8f 100644 (file)
--- a/pod/perlapi.pod
+++ b/pod/perlapi.pod
@@ -2725,7 +2725,7 @@ Found in file sv.h
 
 Returns a boolean indicating whether the SV contains a signed integer.
 
-       void    SvIOK_notUV(SV* sv)
+       bool    SvIOK_notUV(SV* sv)
 
 =for hackers
 Found in file sv.h
@@ -2770,7 +2770,7 @@ Found in file sv.h
 
 Returns a boolean indicating whether the SV contains an unsigned integer.
 
-       void    SvIOK_UV(SV* sv)
+       bool    SvIOK_UV(SV* sv)
 
 =for hackers
 Found in file sv.h
@@ -3349,7 +3349,7 @@ Found in file sv.h
 
 Returns a boolean indicating whether the SV contains UTF-8 encoded data.
 
-       void    SvUTF8(SV* sv)
+       bool    SvUTF8(SV* sv)
 
 =for hackers
 Found in file sv.h

diff --git a/pod/perlxs.pod b/pod/perlxs.pod
index f126ff8..c09947d 100644 (file)
--- a/pod/perlxs.pod
+++ b/pod/perlxs.pod
@@ -276,6 +276,63 @@ some heuristic code which tries to disambiguate between "truly-void"
 and "old-practice-declared-as-void" functions. Hence your code is at
 mercy of this heuristics unless you use C<SV *> as return value.)
 
+=head2 Returning SVs, AVs and HVs through RETVAL
+
+When you're using RETVAL to return an C<SV *>, there's some magic
+going on behind the scenes that should be mentioned. When you're
+manipulating the argument stack using the ST(x) macro, for example,
+you usually have to pay special attention to reference counts. (For
+more about reference counts, see L<perlguts>.) To make your life
+easier, the typemap file automatically makes C<RETVAL> mortal when
+you're returning an C<SV *>. Thus, the following two XSUBs are more
+or less equivalent:
+
+  void
+  alpha()
+      PPCODE:
+          ST(0) = newSVpv("Hello World",0);
+          sv_2mortal(ST(0));
+          XSRETURN(1);
+  
+  SV *
+  beta()
+      CODE:
+          RETVAL = newSVpv("Hello World",0);
+      OUTPUT:
+          RETVAL
+
+This is quite useful as it usually improves readability. While
+this works fine for an C<SV *>, it's unfortunately not as easy
+to have C<AV *> or C<HV *> as a return value. You I<should> be
+able to write:
+
+  AV *
+  array()
+      CODE:
+          RETVAL = newAV();
+          /* do something with RETVAL */
+      OUTPUT:
+          RETVAL
+
+But due to an unfixable bug (fixing it would break lots of existing
+CPAN modules) in the typemap file, the reference count of the C<AV *>
+is not properly decremented. Thus, the above XSUB would leak memory
+whenever it is being called. The same problem exists for C<HV *>.
+
+When you're returning an C<AV *> or a C<HV *>, you have make sure
+their reference count is decremented by making the AV or HV mortal:
+
+  AV *
+  array()
+      CODE:
+          RETVAL = newAV();
+          sv_2mortal((SV*)RETVAL);
+          /* do something with RETVAL */
+      OUTPUT:
+          RETVAL
+
+And also remember that you don't have to do this for an C<SV *>.
+
 =head2 The MODULE Keyword
 
 The MODULE keyword is used to start the XS code and to specify the package

diff --git a/sv.h b/sv.h
index f9268f7..a925ba8 100644 (file)
--- a/sv.h
+++ b/sv.h
@@ -457,13 +457,13 @@ Tells an SV that it is an integer and disables all other OK bits.
 =for apidoc Am|void|SvIOK_only_UV|SV* sv
 Tells and SV that it is an unsigned integer and disables all other OK bits.
 
-=for apidoc Am|void|SvIOK_UV|SV* sv
+=for apidoc Am|bool|SvIOK_UV|SV* sv
 Returns a boolean indicating whether the SV contains an unsigned integer.
 
 =for apidoc Am|void|SvUOK|SV* sv
 Returns a boolean indicating whether the SV contains an unsigned integer.
 
-=for apidoc Am|void|SvIOK_notUV|SV* sv
+=for apidoc Am|bool|SvIOK_notUV|SV* sv
 Returns a boolean indicating whether the SV contains a signed integer.
 
 =for apidoc Am|bool|SvNOK|SV* sv
@@ -603,7 +603,7 @@ Set the length of the string which is in the SV.  See C<SvCUR>.
                                    SvFLAGS(sv) |= (SVf_NOK|SVp_NOK))
 
 /*
-=for apidoc Am|void|SvUTF8|SV* sv
+=for apidoc Am|bool|SvUTF8|SV* sv
 Returns a boolean indicating whether the SV contains UTF-8 encoded data.
 
 =for apidoc Am|void|SvUTF8_on|SV *sv