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
-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()
@@ -331,7 +340,7 @@ their reference count is decremented by making the AV or HV mortal:
       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