NAME

       "Devel::MAT" - Perl Memory Analysis Tool

USER GUIDE

       NEW USERS:

       If you are new to the "Devel::MAT" set of tools, this is probably not the document you want to start
       with. If you are interested in using "Devel::MAT" to help diagnose memory-related problems in a perl
       program you instead want to read the user guide, at Devel::MAT::UserGuide.

       If you are writing tooling modules to extend the abilities of "Devel::MAT" then this may indeed by the
       document for you; read on...

DESCRIPTION

       A "Devel::MAT" instance loads a heapdump file, and provides a container to store analysis tools to work
       on it. Tools may be provided that conform to the Devel::MAT::Tool API, which can help analyse the data
       and interact with the explorer user interface by using the methods in the Devel::MAT::UI package.

   File Format
       The dump file format is still under development, so at present no guarantees are made on whether files
       can be loaded over mismatching versions of "Devel::MAT". However, as of version 0.11 the format should be
       more extensible, allowing new SV fields to be added without breaking loading - older tools will ignore
       new fields and newer tools will just load undef for fields absent in older files. As the distribution
       approaches maturity the format will be made more stable.

CONSTRUCTOR

   load
          $pmat = Devel::MAT->load( $path, %args )

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

METHODS

   dumpfile
          $df = $pmat->dumpfile

       Returns the underlying Devel::MAT::Dumpfile instance backing this analysis object.

   available_tools
          @tools = $pmat->available_tools

       Lists the Devel::MAT::Tool classes that are installed and available.

   load_tool
          $tool = $pmat->load_tool( $name )

       Loads the named Devel::MAT::Tool class.

   has_tool
          $bool = $pmat->has_tool( $name )

       Returns true if the named tool is already loaded.

   run_command
          $pmat->run_command( $inv )

       Runs a tool command given by the Commandable::Invocation instance.

   inref_graph
          $node = $pmat->inref_graph( $sv, %opts )

       Traces the tree of inrefs from $sv back towards the known roots, returning a Devel::MAT::Graph node
       object representing it, within a graph of reverse references back to the known roots.

       This method will load Devel::MAT::Tool::Inrefs if it isn't yet loaded.

       The following named options are recognised:

       depth => INT
           If  specified,  stop  recursing after the specified count. A depth of 1 will only include immediately
           referring SVs, 2 will print the referrers of those, etc.  Nodes with inrefs that were trimmed because
           of this limit will appear to be roots with a special name of "EDEPTH".

       strong => BOOL
       direct => BOOL
           Specifies the type of inrefs followed. By default all inrefs are  followed.   Passing  "strong"  will
           follow only strong direct inrefs. Passing "direct" will follow only direct inrefs.

       elide => BOOL
           If true, attempt to neaten up the output by skipping over certain structures.

           REF()-type SVs will be skipped to their referrant.

           Members of the symbol table will be printed as being a 'root' element of the given symbol name.

           "PAD"s  and  "PADLIST"s  will be skipped to their referring "CODE", giving shorter output for lexical
           variables.

   find_symbol
          $sv = $pmat->find_symbol( $name )

       Attempts to walk the symbol table looking for a symbol of the given name, which must include the sigil.

          $Package::Name::symbol_name => to return a SCALAR SV
          @Package::Name::symbol_name => to return an ARRAY SV
          %Package::Name::symbol_name => to return a HASH SV
          &Package::Name::symbol_name => to return a CODE SV

   find_glob
          $gv = $pmat->find_glob( $name )

       Attempts to walk the symbol table looking for a symbol of the given name, returning the "GLOB" object  if
       found.

   find_stash
          $stash = $pmat->find_stash( $name )

       Attempts to walk the symbol table looking for a stash of the given name.

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>

perl v5.38.2                                       2024-04-01                                    Devel::MAT(3pm)