Devel::MAT::Dumpfile(3pm)

NAME
"Devel::MAT::Dumpfile" - load and analyse a heap dump file

SYNOPSIS
   use Devel::MAT::Dumpfile;

   my $df = Devel::MAT::Dumpfile->load( "path/to/the/file.pmat" );

DESCRIPTION
This module provides a class that loads a heap dump file previously written by Devel::MAT::Dumper. It provides accessor methods to obtain various well-known root starting addresses, or to find arbitrary SVs by address. Each SV is represented by an instance of Devel::MAT::SV.

CONSTRUCTOR

  load
   $df = Devel::MAT::Dumpfile->load( $path, %args );

Loads a heap dump file from the given path, and returns a new "Devel::MAT::Dumpfile" instance representing it.

Takes the following named arguments:

progress => CODE
    If given, should be a CODE reference to a function that will be called regularly during the loading process, and given a status message to update the user.

METHODS

  perlversion
   $version = $df->perlversion;

Returns the version of perl that the heap dump file was created by, as a string in the form 5.14.2.

  endian
   $endian = $df->endian;

Returns the endian direction of the perl that the heap dump was created by, as either "big" or "little".

  uint_len
   $len = $df->uint_len;

Returns the length in bytes of a uint field of the perl that the heap dump was created by.

  ptr_len
   $len = $df->ptr_len;

Returns the length in bytes of a pointer field of the perl that the heap dump was created by.

  nv_len
   $len = $df->nv_len;

Returns the length in bytes of a double field of the perl that the heap dump was created by.

  ithreads
   $ithreads = $df->ithreads;

Returns a boolean indicating whether ithread support was enabled in the perl that the heap dump was created by.

  roots
   %roots = $df->roots;

Returns a key/value pair list giving the names and SVs at each of the roots.

  roots_strong
   %roots = $df->roots_strong;

Returns a key/value pair list giving the names and SVs at each of the roots that count as strong references.

  roots_weak
   %roots = $df->roots_weak;

Returns a key/value pair list giving the names and SVs at each of the roots that count as strong references.

  ROOTS
   $sv = $df->ROOT;

For each of the root names given below, a method exists with that name which returns the SV at that root:

   main_cv
   defstash
   mainstack
   beginav
   checkav
   unitcheckav
   initav
   endav
   strtabhv
   envgv
   incgv
   statgv
   statname
   tmpsv
   defgv
   argvgv
   argvoutgv
   argvout_stack
   fdpidav
   preambleav
   modglobalhv
   regex_padav
   sortstash
   firstgv
   secondgv
   debstash
   stashcache
   isarev
   registered_mros

  root_descriptions
   %rootdescs = $df->root_descriptions;

Returns a key/value pair list giving the (method) name and description text of each of the possible roots.

  root_at
   $addr = $df->root_at( $name );

Returns the SV address of the given named root.

  root
   $sv = $df->root( $name );

Returns the given root SV.

  heap
   @svs = $df->heap;

Returns all of the heap-allocated SVs, in no particular order

  stack
   @svs = $df->stack;

Returns all the SVs on the stack

  contexts
   @ctxs = $df->contexts;

Returns a list of Devel::MAT::Context objects representing the call context stack in the dumpfile.

  sv_at
   $sv = $df->sv_at( $addr );

Returns the SV at the given address, or "undef" if one does not exist.

(Note that this is unambiguous, as a Perl-level "undef" is represented by the immortal "Devel::MAT::SV::UNDEF" SV).

AUTHOR
Paul Evans <leonerd@leonerd.org.uk>