Carp: add comment explaining the fix for perl #131046

In 4764858cb80e76fdba33cc1b3be8fcdef26df754 I added code that
eval's the argument extraction from DB::args() (code written by
both Pali and myself independently).

Unfortunately the commit message for that commit was somewhat
misleading, making it sound like the patch was a complete fix for
the underlying problem of stack-not-refcounted bugs, when in fact
it is actually a workaround, and a not-universally popular one
either due to its incompleteness. For more details of why it is
not popular see Zeframs commentary in
https://rt.perl.org/Public/Bug/Display.html?id=131046

Despite the concerns expressed by Zefram when considered from the
POV of a large enterprise using Carp to trap exceptions from
application code, having Carp throw its own exceptions about
stack-not-refcounted bugs and thus hiding the applications error
data is a significant issue.

So in 4764858cb80e76fdba33cc1b3be8fcdef26df754 we use eval to
handle those cases where Perl /can/ detect a stack-not-refcounted
error, and thus preserve as much of the applications error data
as possible.

This commit adds a comment to Carp which spells all of this out.

3 files changed, 20 insertions, 3 deletions

diff --git a/dist/Carp/Changes b/dist/Carp/Changes
index db3920329b..2b549d97de 100644
--- a/dist/Carp/Changes
+++ b/dist/Carp/Changes
@@ -1,3 +1,9 @@
+version 1.49
+
+ * comment only change, document the change from 1.47 better
+   and create a commit in blead-perl which can be used to
+   reference this issue from the bug report.
+
 version 1.48
 
  * guard against hand-rolled UNIVERSAL::can() implementations
diff --git a/dist/Carp/lib/Carp.pm b/dist/Carp/lib/Carp.pm
index 9956f128d1..419ba9c541 100644
--- a/dist/Carp/lib/Carp.pm
+++ b/dist/Carp/lib/Carp.pm
@@ -116,7 +116,7 @@ BEGIN {
 	;
 }
 
-our $VERSION = '1.48';
+our $VERSION = '1.49';
 $VERSION =~ tr/_//d;
 
 our $MaxEvalLen = 0;
@@ -232,7 +232,18 @@ sub caller_info {
 
     my $sub_name = Carp::get_subname( \%call_info );
     if ( $call_info{has_args} ) {
-        # guard our serialization of the stack from stack refcounting bugs
+        # Guard our serialization of the stack from stack refcounting bugs
+        # NOTE this is NOT a complete solution, we cannot 100% guard against
+        # these bugs.  However in many cases Perl *is* capable of detecting
+        # them and throws an error when it does.  Unfortunately serializing
+        # the arguments on the stack is a perfect way of finding these bugs,
+        # even when they would not affect normal program flow that did not
+        # poke around inside the stack.  Inside of Carp.pm it makes little
+        # sense reporting these bugs, as Carp's job is to report the callers
+        # errors, not the ones it might happen to tickle while doing so.
+        # See: https://rt.perl.org/Public/Bug/Display.html?id=131046
+        # and: https://rt.perl.org/Public/Bug/Display.html?id=52610
+        # for more details and discussion. - Yves
         my @args = map {
                 my $arg;
                 local $@= $@;
diff --git a/dist/Carp/lib/Carp/Heavy.pm b/dist/Carp/lib/Carp/Heavy.pm
index 5188f40d0e..e2b72920a3 100644
--- a/dist/Carp/lib/Carp/Heavy.pm
+++ b/dist/Carp/lib/Carp/Heavy.pm
@@ -2,7 +2,7 @@ package Carp::Heavy;
 
 use Carp ();
 
-our $VERSION = '1.48';
+our $VERSION = '1.49';
 $VERSION =~ tr/_//d;
 
 # Carp::Heavy was merged into Carp in version 1.12.  Any mismatched versions