From dp13@sanger.ac.uk

Please find attached a patch which puts into documentation the advice helpfully given by Zefram and RJBS on #125530. Most of the changes are in perlref, under "Circular References", but there is also an extra paragraph in perlsub which points to perlref.

Daniel

--
The Wellcome Trust Sanger Institute is operated by Genome Research
Limited, a charity registered in England with number 1021457 and a
company registered in England with number 2742969, whose registered
office is 215 Euston Road, London, NW1 2BE.

From dp13@sanger.ac.uk

From 9c878f68fff2ed2193d57963c4c53ea6ee939650 Mon Sep 17 00:00:00 2001
From: Daniel Perrett <dp13@sanger.ac.uk>
Date: Fri, 3 Jul 2015 16:24:02 +0100
Subject: [PATCH] Document how coderefs can be involved in circular references

---
 pod/perlref.pod | 34 +++++++++++++++++++++++++++++++++-
 pod/perlsub.pod |  4 ++++
 2 files changed, 37 insertions(+), 1 deletion(-)

diff --git a/pod/perlref.pod b/pod/perlref.pod
index 8956be5..0721f6a 100644
--- a/pod/perlref.pod
+++ b/pod/perlref.pod
@@ -478,6 +478,7 @@ as:
 
 =head2 Circular References
 X<circular reference> X<reference, circular>
+X<cyclical reference> X<reference, cyclical>
 
 It is possible to create a "circular reference" in Perl, which can lead
 to memory leaks. A circular reference occurs when two references
@@ -492,7 +493,24 @@ You can also create a circular reference with a single variable:
     my $foo;
     $foo = \$foo;
 
-In this case, the reference count for the variables will never reach 0,
+Or with array references:
+
+    my $foo = [];
+    my $bar = [ $foo ];
+    push @$foo, $bar;
+
+Or with code references:
+
+    my $foo;
+    $foo = sub{ print $_[0]; $_[0] && $foo->( $_[0] - 1 ) };
+
+Or with any combination of references:
+
+    my $foo;
+    my $bar = { code => $foo };
+    $foo = sub{ keys %$bar };
+
+In these cases, the reference count for the variables will never reach 0,
 and the references will never be garbage-collected. This can lead to
 memory leaks.
 
@@ -528,6 +546,20 @@ variable that will go out of scope I<first>. That way, the longer-lived
 variable will contain the expected reference until it goes out of
 scope.
 
+To break circularity which involves code references, as of v5.16.0, and
+provided that C<use v5.16.0> or C<use feature 'current_sub'> is in effect,
+you can use C<__SUB__> to perform recursion on the current scope:
+
+    my $foo;
+    $foo = sub{ print $_[0]; $_[0] && __SUB__->( $_[0] - 1 ) };
+
+Alternatively, you can use a weakened reference:
+
+    my $foo;
+    my $foo_weak = \$foo;
+    weaken $foo_weak;
+    $foo = sub{ print $_[0]; $_[0] && $$foo_weak->( $_[0] - 1 ) };
+
 =head2 Symbolic references
 X<reference, symbolic> X<reference, soft>
 X<symbolic reference> X<soft reference>
diff --git a/pod/perlsub.pod b/pod/perlsub.pod
index 48f178f..73a2660 100644
--- a/pod/perlsub.pod
+++ b/pod/perlsub.pod
@@ -796,6 +796,10 @@ functions in that same file declared below them, but are inaccessible
 from outside that file.  This strategy is sometimes used in modules
 to create private variables that the whole module can see.
 
+Like named functions, code references prevent recycling of the variables that
+they use until the code reference itself goes out of scope and is no longer
+referenced. For examples of this, see L<perlref/"Circular References">.
+
 =head2 Temporary Values via local()
 X<local> X<scope, dynamic> X<dynamic scope> X<variable, local>
 X<variable, temporary>
-- 
2.1.4

From @jkeenan

On Mon Jul 06 04​:56​:08 2015, dp13@​sanger.ac.uk wrote​:

Please find attached a patch which puts into documentation the advice
helpfully given by Zefram and RJBS on #125530. Most of the changes are
in perlref, under "Circular References", but there is also an extra
paragraph in perlsub which points to perlref.

Daniel

1. Near the start of your patch file I see​:

#####
=head2 Circular References
X<circular reference> X<reference, circular>
+X<cyclical reference> X<reference, cyclical>
#####

Why do you use the term "cyclical reference" here rather than "circular reference"?

2.

#####
+To break circularity which involves code references, as of v5.16.0, and
+provided that C<use v5.16.0> or C<use feature 'current_sub'> is in effect,
+you can use C<__SUB__> to perform recursion on the current scope​:
#####

This is confusing, as you have two clauses in the same sentence where you use "to + verb" to indicate intentionality​:

* [in order] [t]o break circularity ...

* [in order} to perform recursion ...

This needs untangling.

3.

#####
+Like named functions, code references prevent recycling of the variables that
+they use until the code reference itself goes out of scope and is no longer
+referenced. For examples of this, see L<perlref/"Circular References">.
#####

This sentence is grammatically unbalanced with respect to number. "code references" and "they" are plural, but then you shift to the singular "code reference itself goes ... is". Can you balance?

Thank you very much.

--
James E Keenan (jkeenan@​cpan.org)

The RT System itself - Status changed from 'new' to 'open'

From dp13@sanger.ac.uk

"Why do you use the term "cyclical reference" here rather than "circular reference"?"

a) The fact that I had a brief moment of confusion trying to search for that term, possibly due to either of
b) The use of the term "cyclic" at the top of perlref
c) Devel​::Cycle

This does not replace "circular reference", merely adds another term to the index so that anyone searching for "cyclical" instead of "circular" finds what they want. Happy to omit if there's a reason not to include it, however.

2) Yes, I see how this is awkward. How about​:

=head3 Breaking circularity which involves code references

As of v5.16.0, provided that C<use v5.16.0> or C<use feature 'current_sub'> is in effect, C<__SUB__> will refer to the enclosing code reference, and using it will not create a circular reference​:

3) Good point. How about​:

Like named functions, code references can prevent recycling of the variables that they use. Unlike a named function, however, a code reference can go out of scope and be recycled, potentially allowing variables referenced to be recycled. For examples of this, see L<perlref/"Circular References">.

If you agree, I will resubmit as a patch.

Daniel

-----Original Message-----
From​: James E Keenan via RT [mailto​:perlbug-followup@​perl.org]
Sent​: 07 July 2015 11​:34
To​: Daniel Perrett
Subject​: [perl #125561] [PATCH] Document how coderefs can be involved in circular references

On Mon Jul 06 04​:56​:08 2015, dp13@​sanger.ac.uk wrote​:

Please find attached a patch which puts into documentation the advice
helpfully given by Zefram and RJBS on #125530. Most of the changes are
in perlref, under "Circular References", but there is also an extra
paragraph in perlsub which points to perlref.

Daniel

1. Near the start of your patch file I see​:

#####
=head2 Circular References
X<circular reference> X<reference, circular>
+X<cyclical reference> X<reference, cyclical>
#####

Why do you use the term "cyclical reference" here rather than "circular reference"?

2.

#####
+To break circularity which involves code references, as of v5.16.0, and
+provided that C<use v5.16.0> or C<use feature 'current_sub'> is in
+effect, you can use C<__SUB__> to perform recursion on the current scope​:
#####

This is confusing, as you have two clauses in the same sentence where you use "to + verb" to indicate intentionality​:

* [in order] [t]o break circularity ...

* [in order} to perform recursion ...

This needs untangling.

3.

#####
+Like named functions, code references prevent recycling of the
+variables that they use until the code reference itself goes out of
+scope and is no longer referenced. For examples of this, see L<perlref/"Circular References">.
#####

This sentence is grammatically unbalanced with respect to number. "code references" and "they" are plural, but then you shift to the singular "code reference itself goes ... is". Can you balance?

Thank you very much.

--
James E Keenan (jkeenan@​cpan.org)

From @demerphq

On 8 Jul 2015 20​:20, "Daniel Perrett" <dp13@​sanger.ac.uk> wrote​:

"Why do you use the term "cyclical reference" here rather than "circular
reference"?"

a) The fact that I had a brief moment of confusion trying to search for
that term, possibly due to either of
b) The use of the term "cyclic" at the top of perlref
c) Devel​::Cycle

This does not replace "circular reference", merely adds another term to
the index so that anyone searching for "cyclical" instead of "circular"
finds what they want. Happy to omit if there's a reason not to include it,
however.

Fwiw I consider reference cycle to be the correct term, circular reference
is imo slang.

Yves

2) Yes, I see how this is awkward. How about​:

=head3 Breaking circularity which involves code references

As of v5.16.0, provided that C<use v5.16.0> or C<use feature
'current_sub'> is in effect, C<__SUB__> will refer to the enclosing code
reference, and using it will not create a circular reference​:

3) Good point. How about​:

Like named functions, code references can prevent recycling of the
variables that they use. Unlike a named function, however, a code reference
can go out of scope and be recycled, potentially allowing variables
referenced to be recycled. For examples of this, see L<perlref/"Circular
References">.

If you agree, I will resubmit as a patch.

Daniel

-----Original Message-----
From​: James E Keenan via RT [mailto​:perlbug-followup@​perl.org]
Sent​: 07 July 2015 11​:34
To​: Daniel Perrett
Subject​: [perl #125561] [PATCH] Document how coderefs can be involved in
circular references

On Mon Jul 06 04​:56​:08 2015, dp13@​sanger.ac.uk wrote​:

Please find attached a patch which puts into documentation the advice
helpfully given by Zefram and RJBS on #125530. Most of the changes are
in perlref, under "Circular References", but there is also an extra
paragraph in perlsub which points to perlref.

Daniel

1. Near the start of your patch file I see​:

#####
=head2 Circular References
X<circular reference> X<reference, circular>
+X<cyclical reference> X<reference, cyclical>
#####

Why do you use the term "cyclical reference" here rather than "circular
reference"?

2.

#####
+To break circularity which involves code references, as of v5.16.0, and
+provided that C<use v5.16.0> or C<use feature 'current_sub'> is in
+effect, you can use C<__SUB__> to perform recursion on the current scope​:
#####

This is confusing, as you have two clauses in the same sentence where you
use "to + verb" to indicate intentionality​:

* [in order] [t]o break circularity ...

* [in order} to perform recursion ...

This needs untangling.

3.

#####
+Like named functions, code references prevent recycling of the
+variables that they use until the code reference itself goes out of
+scope and is no longer referenced. For examples of this, see
L<perlref/"Circular References">.
#####

This sentence is grammatically unbalanced with respect to number. "code
references" and "they" are plural, but then you shift to the singular "code
reference itself goes ... is". Can you balance?

Thank you very much.

--
James E Keenan (jkeenan@​cpan.org)

From @tonycoz

On Wed Jul 08 11​:20​:37 2015, dp13@​sanger.ac.uk wrote​:

"Why do you use the term "cyclical reference" here rather than
"circular reference"?"

a) The fact that I had a brief moment of confusion trying to search
for that term, possibly due to either of
b) The use of the term "cyclic" at the top of perlref
c) Devel​::Cycle

This does not replace "circular reference", merely adds another term
to the index so that anyone searching for "cyclical" instead of
"circular" finds what they want. Happy to omit if there's a reason not
to include it, however.

I think instead of replacing the current two index entries, it would be better to add to them, so it becomes​:

X<circular reference> X<reference, circular> X<cyclical reference> X<reference, cyclical>

Tony

From @rjbs

* Tony Cook via RT <perlbug-followup@​perl.org> [2015-07-22T02​:03​:46]

I think instead of replacing the current two index entries, it would be
better to add to them, so it becomes​:

X<circular reference> X<reference, circular> X<cyclical reference> X<reference, cyclical>

The patch does add, rather than replace​:

  =head2 Circular References
  X<circular reference> X<reference, circular>
  +X<cyclical reference> X<reference, cyclical>

Note that the third line is + but the second line is not -.

--
rjbs