README
1NAME
2
3 Devel::MAT - Perl Memory Analysis Tool
4
5USER 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
17DESCRIPTION
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
35CONSTRUCTOR
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
44METHODS
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 run_command
66
67 $pmat->run_command( $inv )
68
69 Runs a tool command given by the Commandable::Invocation instance.
70
71 inref_graph
72
73 $node = $pmat->inref_graph( $sv, %opts )
74
75 Traces the tree of inrefs from $sv back towards the known roots,
76 returning a Devel::MAT::Graph node object representing it, within a
77 graph of reverse references back to the known roots.
78
79 This method will load Devel::MAT::Tool::Inrefs if it isn't yet loaded.
80
81 The following named options are recognised:
82
83 depth => INT
84
85 If specified, stop recursing after the specified count. A depth of 1
86 will only include immediately referring SVs, 2 will print the
87 referrers of those, etc. Nodes with inrefs that were trimmed because
88 of this limit will appear to be roots with a special name of EDEPTH.
89
90 strong => BOOL
91
92 direct => BOOL
93
94 Specifies the type of inrefs followed. By default all inrefs are
95 followed. Passing strong will follow only strong direct inrefs.
96 Passing direct will follow only direct inrefs.
97
98 elide => BOOL
99
100 If true, attempt to neaten up the output by skipping over certain
101 structures.
102
103 REF()-type SVs will be skipped to their referrant.
104
105 Members of the symbol table will be printed as being a 'root' element
106 of the given symbol name.
107
108 PADs and PADLISTs will be skipped to their referring CODE, giving
109 shorter output for lexical variables.
110
111 find_symbol
112
113 $sv = $pmat->find_symbol( $name )
114
115 Attempts to walk the symbol table looking for a symbol of the given
116 name, which must include the sigil.
117
118 $Package::Name::symbol_name => to return a SCALAR SV
119 @Package::Name::symbol_name => to return an ARRAY SV
120 %Package::Name::symbol_name => to return a HASH SV
121 &Package::Name::symbol_name => to return a CODE SV
122
123 find_glob
124
125 $gv = $pmat->find_glob( $name )
126
127 Attempts to walk the symbol table looking for a symbol of the given
128 name, returning the GLOB object if found.
129
130 find_stash
131
132 $stash = $pmat->find_stash( $name )
133
134 Attempts to walk the symbol table looking for a stash of the given
135 name.
136
137AUTHOR
138
139 Paul Evans <leonerd@leonerd.org.uk>
140
141