| 1 |
NAME |
| 2 |
|
| 3 |
Devel::MAT - Perl Memory Analysis Tool |
| 4 |
|
| 5 |
USER GUIDE |
| 6 |
|
| 7 |
NEW USERS: |
| 8 |
|
| 9 |
If you are new to the Devel::MAT set of tools, this is probably not the |
| 10 |
document you want to start with. If you are interested in using |
| 11 |
Devel::MAT to help diagnose memory-related problems in a perl program |
| 12 |
you instead want to read the user guide, at Devel::MAT::UserGuide. |
| 13 |
|
| 14 |
If you are writing tooling modules to extend the abilities of |
| 15 |
Devel::MAT then this may indeed by the document for you; read on... |
| 16 |
|
| 17 |
DESCRIPTION |
| 18 |
|
| 19 |
A Devel::MAT instance loads a heapdump file, and provides a container |
| 20 |
to store analysis tools to work on it. Tools may be provided that |
| 21 |
conform to the Devel::MAT::Tool API, which can help analyse the data |
| 22 |
and interact with the explorer user interface by using the methods in |
| 23 |
the Devel::MAT::UI package. |
| 24 |
|
| 25 |
File Format |
| 26 |
|
| 27 |
The dump file format is still under development, so at present no |
| 28 |
guarantees are made on whether files can be loaded over mismatching |
| 29 |
versions of Devel::MAT. However, as of version 0.11 the format should |
| 30 |
be more extensible, allowing new SV fields to be added without breaking |
| 31 |
loading - older tools will ignore new fields and newer tools will just |
| 32 |
load undef for fields absent in older files. As the distribution |
| 33 |
approaches maturity the format will be made more stable. |
| 34 |
|
| 35 |
CONSTRUCTOR |
| 36 |
|
| 37 |
load |
| 38 |
|
| 39 |
$pmat = Devel::MAT->load( $path, %args ); |
| 40 |
|
| 41 |
Loads a heap dump file from the given path, and returns a new |
| 42 |
Devel::MAT instance wrapping it. |
| 43 |
|
| 44 |
METHODS |
| 45 |
|
| 46 |
dumpfile |
| 47 |
|
| 48 |
$df = $pmat->dumpfile; |
| 49 |
|
| 50 |
Returns the underlying Devel::MAT::Dumpfile instance backing this |
| 51 |
analysis object. |
| 52 |
|
| 53 |
available_tools |
| 54 |
|
| 55 |
@tools = $pmat->available_tools; |
| 56 |
|
| 57 |
Lists the Devel::MAT::Tool classes that are installed and available. |
| 58 |
|
| 59 |
load_tool |
| 60 |
|
| 61 |
$tool = $pmat->load_tool( $name ); |
| 62 |
|
| 63 |
Loads the named Devel::MAT::Tool class. |
| 64 |
|
| 65 |
has_tool |
| 66 |
|
| 67 |
$bool = $pmat->has_tool( $name ); |
| 68 |
|
| 69 |
Returns true if the named tool is already loaded. |
| 70 |
|
| 71 |
run_command |
| 72 |
|
| 73 |
$pmat->run_command( $inv ); |
| 74 |
|
| 75 |
Runs a tool command given by the Commandable::Invocation instance. |
| 76 |
|
| 77 |
inref_graph |
| 78 |
|
| 79 |
$node = $pmat->inref_graph( $sv, %opts ); |
| 80 |
|
| 81 |
Traces the tree of inrefs from $sv back towards the known roots, |
| 82 |
returning a Devel::MAT::Graph node object representing it, within a |
| 83 |
graph of reverse references back to the known roots. |
| 84 |
|
| 85 |
This method will load Devel::MAT::Tool::Inrefs if it isn't yet loaded. |
| 86 |
|
| 87 |
The following named options are recognised: |
| 88 |
|
| 89 |
depth => INT |
| 90 |
|
| 91 |
If specified, stop recursing after the specified count. A depth of 1 |
| 92 |
will only include immediately referring SVs, 2 will print the |
| 93 |
referrers of those, etc. Nodes with inrefs that were trimmed because |
| 94 |
of this limit will appear to be roots with a special name of EDEPTH. |
| 95 |
|
| 96 |
strong => BOOL |
| 97 |
|
| 98 |
direct => BOOL |
| 99 |
|
| 100 |
Specifies the type of inrefs followed. By default all inrefs are |
| 101 |
followed. Passing strong will follow only strong direct inrefs. |
| 102 |
Passing direct will follow only direct inrefs. |
| 103 |
|
| 104 |
elide => BOOL |
| 105 |
|
| 106 |
If true, attempt to neaten up the output by skipping over certain |
| 107 |
structures. |
| 108 |
|
| 109 |
REF()-type SVs will be skipped to their referrant. |
| 110 |
|
| 111 |
Members of the symbol table will be printed as being a 'root' element |
| 112 |
of the given symbol name. |
| 113 |
|
| 114 |
PADs and PADLISTs will be skipped to their referring CODE, giving |
| 115 |
shorter output for lexical variables. |
| 116 |
|
| 117 |
find_symbol |
| 118 |
|
| 119 |
$sv = $pmat->find_symbol( $name ); |
| 120 |
|
| 121 |
Attempts to walk the symbol table looking for a symbol of the given |
| 122 |
name, which must include the sigil. |
| 123 |
|
| 124 |
$Package::Name::symbol_name => to return a SCALAR SV |
| 125 |
@Package::Name::symbol_name => to return an ARRAY SV |
| 126 |
%Package::Name::symbol_name => to return a HASH SV |
| 127 |
&Package::Name::symbol_name => to return a CODE SV |
| 128 |
|
| 129 |
find_glob |
| 130 |
|
| 131 |
$gv = $pmat->find_glob( $name ); |
| 132 |
|
| 133 |
Attempts to walk the symbol table looking for a symbol of the given |
| 134 |
name, returning the GLOB object if found. |
| 135 |
|
| 136 |
find_stash |
| 137 |
|
| 138 |
$stash = $pmat->find_stash( $name ); |
| 139 |
|
| 140 |
Attempts to walk the symbol table looking for a stash of the given |
| 141 |
name. |
| 142 |
|
| 143 |
AUTHOR |
| 144 |
|
| 145 |
Paul Evans <[email protected]> |
| 146 |
|