This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Document the new, fixed AV/etc typemaps
authorSteffen Mueller <smueller@cpan.org>
Thu, 20 Oct 2011 06:24:35 +0000 (08:24 +0200)
committerSteffen Mueller <smueller@cpan.org>
Thu, 20 Oct 2011 06:24:35 +0000 (08:24 +0200)
dist/ExtUtils-ParseXS/lib/perlxs.pod

index 085536e..38068c3 100644 (file)
@@ -317,10 +317,19 @@ able to write:
 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
 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 *>.
+whenever it is being called. The same problem exists for C<HV *>,
+C<CV *>, and C<SVREF> (which indicates a scalar reference, not
+a general C<SV *>).
+In XS code on perls starting with perl 5.16, you can override the
+typemaps for any of these types with a version that has proper
+handling of refcounts. In your C<TYPEMAP> section, do
 
 
-When you're returning an C<AV *> or a C<HV *>, you have to make sure
-their reference count is decremented by making the AV or HV mortal:
+  AV*  T_AVREF_REFCOUNT_FIXED
+
+to get the repaired variant. For backward compatibility with older
+versions of perl, you can instead decrement the reference count
+manually when you're returning one of the aforementioned
+types using C<sv_2mortal>:
 
   AV *
   array()
 
   AV *
   array()
@@ -331,7 +340,7 @@ their reference count is decremented by making the AV or HV mortal:
       OUTPUT:
           RETVAL
 
       OUTPUT:
           RETVAL
 
-And also remember that you don't have to do this for an C<SV *>.
+Remember that you don't have to do this for an C<SV *>.
 
 =head2 The MODULE Keyword
 
 
 =head2 The MODULE Keyword