.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Devel::Cycle 3pm"
.TH Devel::Cycle 3pm "2012-03-21" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Devel::Cycle \- Find memory cycles in objects
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 12
\&  #!/usr/bin/perl
\&  use Devel::Cycle;
\&  my $test = {fred   => [qw(a b c d e)],
\&            ethel  => [qw(1 2 3 4 5)],
\&            george => {martha => 23,
\&                       agnes  => 19}
\&           };
\&  $test\->{george}{phyllis} = $test;
\&  $test\->{fred}[3]      = $test\->{george};
\&  $test\->{george}{mary} = $test\->{fred};
\&  find_cycle($test);
\&  exit 0;
\&
\&  # output:
\&
\&  Cycle (1):
\&                        $A\->{\*(Aqgeorge\*(Aq} => \e%B
\&                       $B\->{\*(Aqphyllis\*(Aq} => \e%A
\&
\&  Cycle (2):
\&                        $A\->{\*(Aqgeorge\*(Aq} => \e%B
\&                          $B\->{\*(Aqmary\*(Aq} => \e@A
\&                               $A\->[3] => \e%B
\&
\&  Cycle (3):
\&                          $A\->{\*(Aqfred\*(Aq} => \e@A
\&                               $A\->[3] => \e%B
\&                       $B\->{\*(Aqphyllis\*(Aq} => \e%A
\&
\&  Cycle (4):
\&                          $A\->{\*(Aqfred\*(Aq} => \e@A
\&                               $A\->[3] => \e%B
\&                          $B\->{\*(Aqmary\*(Aq} => \e@A
\&  
\&  # you can also check weakened references
\&  weaken($test\->{george}\->{phyllis});
\&  find_weakened_cycle($test);
\&  exit 0;
\&
\&  # output:
\&  
\&  Cycle (1):
\&                        $A\->{\*(Aqgeorge\*(Aq} => \e%B                           
\&                          $B\->{\*(Aqmary\*(Aq} => \e@C                           
\&                               $C\->[3] => \e%B                           
\&
\&  Cycle (2):
\&                        $A\->{\*(Aqgeorge\*(Aq} => \e%B                           
\&                   w\-> $B\->{\*(Aqphyllis\*(Aq} => \e%A                           
\&
\&  Cycle (3):
\&                          $A\->{\*(Aqfred\*(Aq} => \e@C                           
\&                               $C\->[3] => \e%B                           
\&                          $B\->{\*(Aqmary\*(Aq} => \e@C                           
\&
\&  Cycle (4):
\&                          $A\->{\*(Aqfred\*(Aq} => \e@C                           
\&                               $C\->[3] => \e%B                           
\&                   w\-> $B\->{\*(Aqphyllis\*(Aq} => \e%A
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is a simple developer's tool for finding circular references in
objects and other types of references.  Because of Perl's
reference-count based memory management, circular references will
cause memory leaks.
.SS "\s-1EXPORT\s0"
.IX Subsection "EXPORT"
The \fIfind_cycle()\fR and \fIfind_weakened_cycle()\fR subroutine are exported by default.
.IP "find_cycle($object_reference,[$callback])" 4
.IX Item "find_cycle($object_reference,[$callback])"
The \fIfind_cycle()\fR function will traverse the object reference and print
a report to \s-1STDOUT\s0 identifying any memory cycles it finds.
.Sp
If an optional callback code reference is provided, then this callback
will be invoked on each cycle that is found.  The callback will be
passed an array reference pointing to a list of lists with the
following format:
.Sp
.Vb 5
\& $arg = [ [\*(AqREFTYPE\*(Aq,$index,$reference,$reference_value],
\&          [\*(AqREFTYPE\*(Aq,$index,$reference,$reference_value],
\&          [\*(AqREFTYPE\*(Aq,$index,$reference,$reference_value],
\&           ...
\&        ]
.Ve
.Sp
Each element in the array reference describes one edge in the memory
cycle.  '\s-1REFTYPE\s0' describes the type of the reference and is one of
\&'\s-1SCALAR\s0','\s-1ARRAY\s0' or '\s-1HASH\s0'.  \f(CW$index\fR is the index affected by the
reference, and is undef for a scalar, an integer for an array
reference, or a hash key for a hash.  \f(CW$reference\fR is the memory
reference, and \f(CW$reference_value\fR is its dereferenced value.  For
example, if the edge is an \s-1ARRAY\s0, then the following relationship
holds:
.Sp
.Vb 1
\&   $reference\->[$index] eq $reference_value
.Ve
.Sp
The first element of the array reference is the \f(CW$object_reference\fR that
you passed to \fIfind_cycle()\fR and may not be directly involved in the
cycle.
.Sp
If a reference is a weak ref produced using Scalar::Util's \fIweaken()\fR
function then it won't contribute to cycles.
.IP "find_weakened_cycle($object_reference,[$callback])" 4
.IX Item "find_weakened_cycle($object_reference,[$callback])"
The \fIfind_weakened_cycle()\fR function will traverse the object reference and print
a report to \s-1STDOUT\s0 identifying any memory cycles it finds, \fIincluding\fR any weakened
cycles produced using Scalar::Util's \fIweaken()\fR.
.Sp
If an optional callback code reference is provided, then this callback
will be invoked on each cycle that is found.  The callback will be
passed an array reference pointing to a list of lists with the
following format:
.Sp
.Vb 5
\& $arg = [ [\*(AqREFTYPE\*(Aq,$index,$reference,$reference_value,$is_weakened],
\&          [\*(AqREFTYPE\*(Aq,$index,$reference,$reference_value,$is_weakened],
\&          [\*(AqREFTYPE\*(Aq,$index,$reference,$reference_value,$is_weakened],
\&           ...
\&        ]
.Ve
.Sp
Each element in the array reference describes one edge in the memory
cycle.  '\s-1REFTYPE\s0' describes the type of the reference and is one of
\&'\s-1SCALAR\s0','\s-1ARRAY\s0' or '\s-1HASH\s0'.  \f(CW$index\fR is the index affected by the
reference, and is undef for a scalar, an integer for an array
reference, or a hash key for a hash.  \f(CW$reference\fR is the memory
reference, and \f(CW$reference_value\fR is its dereferenced value. \f(CW$is_weakened\fR
is a boolean specifying if the reference is weakened or not. For
example, if the edge is an \s-1ARRAY\s0, then the following relationship
holds:
.Sp
.Vb 1
\&   $reference\->[$index] eq $reference_value
.Ve
.Sp
The first element of the array reference is the \f(CW$object_reference\fR that
you passed to \fIfind_cycle()\fR and may not be directly involved in the
cycle.
.SS "Cycle Report Formats"
.IX Subsection "Cycle Report Formats"
The default callback prints out a trace of each cycle it finds.  You
can control the format of the trace by setting the package variable
\&\f(CW$Devel::Cycle::FORMATTING\fR to one of \*(L"raw,\*(R" \*(L"cooked,\*(R" or \*(L"roasted\*(R".
.PP
The \*(L"raw\*(R" format prints out anonymous memory references using standard
Perl memory location nomenclature.  For example, a \*(L"Foo::Bar\*(R" object
that points to an ordinary hash will appear in the trace like this:
.PP
.Vb 1
\&        Foo::Bar=HASH(0x8124394)\->{\*(Aqphyllis\*(Aq} => HASH(0x81b4a90)
.Ve
.PP
The \*(L"cooked\*(R" format (the default), uses short names for anonymous
memory locations, beginning with \*(L"A\*(R" and moving upward with the magic
++ operator.  This leads to a much more readable display:
.PP
.Vb 1
\&        $Foo::Bar=B\->{\*(Aqphyllis\*(Aq} => \e%A
.Ve
.PP
The \*(L"roasted\*(R" format is similar to the \*(L"cooked\*(R" format, except that
object references are formatted slightly differently:
.PP
.Vb 1
\&        $Foo::Bar::B\->{\*(Aqphyllis\*(Aq} => \e%A
.Ve
.PP
If a reference is a weakened ref, then it will have a 'w\->' prepended to
it, like this:
.PP
.Vb 1
\&        w\-> $Foo::Bar::B\->{\*(Aqphyllis\*(Aq} => \e%A
.Ve
.PP
For your convenience, \f(CW$Devel::Cycle::FORMATTING\fR can be imported:
.PP
.Vb 2
\&       use Devel::Cycle qw(:DEFAULT $FORMATTING);
\&       $FORMATTING = \*(Aqraw\*(Aq;
.Ve
.PP
Alternatively, you can control the formatting at compile time by
passing one of the options \-raw, \-cooked, or \-roasted to \*(L"use\*(R" as
illustrated here:
.PP
.Vb 1
\&  use Devel::Cycle \-raw;
.Ve
.SS "Code references (closures)"
.IX Subsection "Code references (closures)"
If the PadWalker module is installed, Devel::Cycle will also report
cycles in code closures. If PadWalker is not installed and
Devel::Cycle detects a \s-1CODE\s0 reference in one of the data structures,
it will warn (once per data structure) that it cannot inspect the \s-1CODE\s0
unless PadWalker is available. You can turn this warning off by
passing \-quiet to Devel::Cycle at compile time:
.PP
.Vb 1
\& use Devel::Cycle \-quiet;
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Test::Memory::Cycle
Devel::Leak
Scalar::Util
.SH "AUTHOR"
.IX Header "AUTHOR"
Lincoln Stein, <lstein@cshl.edu>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2003 by Lincoln Stein
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.2 or,
at your option, any later version of Perl 5 you may have available.