GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  DEVEL::CYCLE (3)

.ds Aq ’

NAME

Devel::Cycle - Find memory cycles in objects

CONTENTS

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):
                        $A->{george} => \%B
                       $B->{phyllis} => \%A

  Cycle (2):
                        $A->{george} => \%B
                          $B->{mary} => \@A
                               $A->[3] => \%B

  Cycle (3):
                          $A->{fred} => \@A
                               $A->[3] => \%B
                       $B->{phyllis} => \%A

  Cycle (4):
                          $A->{fred} => \@A
                               $A->[3] => \%B
                          $B->{mary} => \@A
 
  # you can also check weakened references
  weaken($test->{george}->{phyllis});
  find_weakened_cycle($test);
  exit 0;

  # output:
 
  Cycle (1):
                        $A->{george} => \%B                          
                          $B->{mary} => \@C                          
                               $C->[3] => \%B                          

  Cycle (2):
                        $A->{george} => \%B                          
                   w-> $B->{phyllis} => \%A                          

  Cycle (3):
                          $A->{fred} => \@C                          
                               $C->[3] => \%B                          
                          $B->{mary} => \@C                          

  Cycle (4):
                          $A->{fred} => \@C                          
                               $C->[3] => \%B                          
                   w-> $B->{phyllis} => \%A



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.

    EXPORT

The find_cycle() and find_weakened_cycle() subroutine are 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.

find_weakened_cycle($object_reference,[$callback]) The find_weakened_cycle() function will traverse the object reference and print a report to STDOUT identifying any memory cycles it finds, including any weakened cycles produced using Scalar::Util’s weaken().

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,$is_weakened],
          [REFTYPE,$index,$reference,$reference_value,$is_weakened],
          [REFTYPE,$index,$reference,$reference_value,$is_weakened],
           ...
        ]



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. $is_weakened is a boolean specifying if the reference is weakened or not. 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.

    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 $Devel::Cycle::FORMATTING to one of raw, cooked, or roasted.

The raw format prints out anonymous memory references using standard Perl memory location nomenclature. For example, a Foo::Bar object that points to an ordinary hash will appear in the trace like this:



        Foo::Bar=HASH(0x8124394)->{phyllis} => HASH(0x81b4a90)



The cooked format (the default), uses short names for anonymous memory locations, beginning with A and moving upward with the magic ++ operator. This leads to a much more readable display:



        $Foo::Bar=B->{phyllis} => \%A



The roasted format is similar to the cooked format, except that object references are formatted slightly differently:



        $Foo::Bar::B->{phyllis} => \%A



If a reference is a weakened ref, then it will have a ’w->’ prepended to it, like this:



        w-> $Foo::Bar::B->{phyllis} => \%A



For your convenience, $Devel::Cycle::FORMATTING can be imported:



       use Devel::Cycle qw(:DEFAULT $FORMATTING);
       $FORMATTING = raw;



Alternatively, you can control the formatting at compile time by passing one of the options -raw, -cooked, or -roasted to use as illustrated here:



  use Devel::Cycle -raw;



    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 CODE reference in one of the data structures, it will warn (once per data structure) that it cannot inspect the CODE unless PadWalker is available. You can turn this warning off by passing -quiet to Devel::Cycle at compile time:



 use Devel::Cycle -quiet;



SEE ALSO

Test::Memory::Cycle Devel::Leak Scalar::Util

DEVELOPING

https://github.com/lstein/Devel-Cycle. Please contribute to the code base by sending pull requests. Use GitHub for bug reports and feature requests.

AUTHOR

Lincoln Stein, <lincoln.stein@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2003-2014 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.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 DEVEL::CYCLE (3) 2014-11-14

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.