Add builtin:: funcs for handling weakrefs

Also, ensure that B::Deparse understands the OA_TARGMY optimisation of
OP_ISBOOL

1 files changed, 26 insertions, 1 deletions

diff --git a/lib/builtin.pm b/lib/builtin.pm
index 461f7ca5fe..2be1cdb455 100644
--- a/lib/builtin.pm
+++ b/lib/builtin.pm
@@ -16,7 +16,10 @@ builtin - Perl pragma to import built-in utility functions
 
 =head1 SYNOPSIS
 
-    use builtin qw( true false isbool );
+    use builtin qw(
+        true false isbool
+        weaken unweaken isweak
+    );
 
 =head1 DESCRIPTION
 
@@ -95,6 +98,28 @@ function (such as C<true> or C<isbool> itself), boolean-returning operator
 (such as the C<eq> or C<==> comparison tests or the C<!> negation operator),
 or any variable containing one of these results.
 
+=head2 weaken
+
+    weaken($ref);
+
+Weakens a reference. A weakened reference does not contribute to the reference
+count of its referent. If only weaekend references to it remain then it will
+be disposed of, and all remaining weak references will have their value set to
+C<undef>.
+
+=head2 unweaken
+
+    unweaken($ref);
+
+Strengthens a reference, undoing the effects of a previous call to L</weaken>.
+
+=head2 isweak
+
+    $bool = isweak($ref);
+
+Returns true when given a weakened reference, or false if not a reference or
+not weak.
+
 =head1 SEE ALSO
 
 L<perlop>, L<perlfunc>, L<Scalar::Util>