NAME

Devel::Cycle - Find memory cycles in objects

SYNOPSIS

  #!/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):
        HASH(0x8171d30)->{george} => HASH(0x8171d00)
        HASH(0x8171d00)->{phyllis} => HASH(0x8171d30)

 Cycle (2):
        HASH(0x8171d30)->{george} => HASH(0x8171d00)
        HASH(0x8171d00)->{mary} => ARRAY(0x814be60)
        ARRAY(0x814be60)->[3] => HASH(0x8171d00)

 Cycle (3):
        HASH(0x8171d30)->{fred} => ARRAY(0x814be60)
        ARRAY(0x814be60)->[3] => HASH(0x8171d00)
        HASH(0x8171d00)->{phyllis} => HASH(0x8171d30)

 Cycle (4):
        HASH(0x8171d30)->{fred} => ARRAY(0x814be60)
        ARRAY(0x814be60)->[3] => HASH(0x8171d00)
        HASH(0x8171d00)->{mary} => ARRAY(0x814be60)

DESCRIPTION

This is a simple developer's tool for finding cycles in objects and other types of references. Because of Perl's reference-count based memory management, cycles will cause memory leaks.

EXPORT

The find_cycle() subroutine is exported by default.

find_cycle($object_reference,[$callback])

The find_cycle() function will traverse the object reference and print a report to STDOUT identifying any memory cycles it finds.

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:

 $arg = [ ['REFTYPE',$index,$reference,$reference_value],
          ['REFTYPE',$index,$reference,$reference_value],
          ['REFTYPE',$index,$reference,$reference_value],
           ...
        ]

Each element in the array reference describes one edge in the memory cycle. 'REFTYPE' describes the type of the reference and is one of 'SCALAR','ARRAY' or 'HASH'. $index 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. $reference is the memory reference, and $reference_value is its dereferenced value. For example, if the edge is an ARRAY, then the following relationship holds:

   $reference->[$index] eq $reference_value

The first element of the array reference is the $object_reference that you pased to find_cycle() and may not be directly involved in the cycle.

If a reference is a weak ref produced using Scalar::Util's weaken() function then it won't contribute to cycles.

SEE ALSO

Devel::Leak

Scalar::Util

AUTHOR

Lincoln Stein, <lstein@cshl.edu>

COPYRIGHT AND LICENSE

Copyright (C) 2003 by Lincoln Stein

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.