Debian Codegraph @

README

raw
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