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" );

        TODO

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>