.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Devel::MAT 3pm" .TH Devel::MAT 3pm "2023-03-26" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" "Devel::MAT" \- Perl Memory Analysis Tool .SH "USER GUIDE" .IX Header "USER GUIDE" \&\fB\s-1NEW USERS:\s0\fR .PP If you are new to the \f(CW\*(C`Devel::MAT\*(C'\fR set of tools, this is probably not the document you want to start with. If you are interested in using \f(CW\*(C`Devel::MAT\*(C'\fR to help diagnose memory-related problems in a \fIperl\fR program you instead want to read the user guide, at Devel::MAT::UserGuide. .PP If you are writing tooling modules to extend the abilities of \f(CW\*(C`Devel::MAT\*(C'\fR then this may indeed by the document for you; read on... .SH "DESCRIPTION" .IX Header "DESCRIPTION" A \f(CW\*(C`Devel::MAT\*(C'\fR 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 \s-1API,\s0 which can help analyse the data and interact with the explorer user interface by using the methods in the Devel::MAT::UI package. .SS "File Format" .IX Subsection "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 \&\f(CW\*(C`Devel::MAT\*(C'\fR. However, as of version 0.11 the format should be more extensible, allowing new \s-1SV\s0 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. .SH "CONSTRUCTOR" .IX Header "CONSTRUCTOR" .SS "load" .IX Subsection "load" .Vb 1 \& $pmat = Devel::MAT\->load( $path, %args ) .Ve .PP Loads a heap dump file from the given path, and returns a new \f(CW\*(C`Devel::MAT\*(C'\fR instance wrapping it. .SH "METHODS" .IX Header "METHODS" .SS "dumpfile" .IX Subsection "dumpfile" .Vb 1 \& $df = $pmat\->dumpfile .Ve .PP Returns the underlying Devel::MAT::Dumpfile instance backing this analysis object. .SS "available_tools" .IX Subsection "available_tools" .Vb 1 \& @tools = $pmat\->available_tools .Ve .PP Lists the Devel::MAT::Tool classes that are installed and available. .SS "load_tool" .IX Subsection "load_tool" .Vb 1 \& $tool = $pmat\->load_tool( $name ) .Ve .PP Loads the named Devel::MAT::Tool class. .SS "has_tool" .IX Subsection "has_tool" .Vb 1 \& $bool = $pmat\->has_tool( $name ) .Ve .PP Returns true if the named tool is already loaded. .SS "run_command" .IX Subsection "run_command" .Vb 1 \& $pmat\->run_command( $inv ) .Ve .PP Runs a tool command given by the Commandable::Invocation instance. .SS "inref_graph" .IX Subsection "inref_graph" .Vb 1 \& $node = $pmat\->inref_graph( $sv, %opts ) .Ve .PP Traces the tree of inrefs from \f(CW$sv\fR 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. .PP This method will load Devel::MAT::Tool::Inrefs if it isn't yet loaded. .PP The following named options are recognised: .IP "depth => \s-1INT\s0" 4 .IX Item "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 \f(CW\*(C`EDEPTH\*(C'\fR. .IP "strong => \s-1BOOL\s0" 4 .IX Item "strong => BOOL" .PD 0 .IP "direct => \s-1BOOL\s0" 4 .IX Item "direct => BOOL" .PD Specifies the type of inrefs followed. By default all inrefs are followed. Passing \f(CW\*(C`strong\*(C'\fR will follow only strong direct inrefs. Passing \f(CW\*(C`direct\*(C'\fR will follow only direct inrefs. .IP "elide => \s-1BOOL\s0" 4 .IX Item "elide => BOOL" If true, attempt to neaten up the output by skipping over certain structures. .Sp \&\f(CW\*(C`REF()\*(C'\fR\-type SVs will be skipped to their referrant. .Sp Members of the symbol table will be printed as being a 'root' element of the given symbol name. .Sp \&\f(CW\*(C`PAD\*(C'\fRs and \f(CW\*(C`PADLIST\*(C'\fRs will be skipped to their referring \f(CW\*(C`CODE\*(C'\fR, giving shorter output for lexical variables. .SS "find_symbol" .IX Subsection "find_symbol" .Vb 1 \& $sv = $pmat\->find_symbol( $name ) .Ve .PP Attempts to walk the symbol table looking for a symbol of the given name, which must include the sigil. .PP .Vb 4 \& $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 .Ve .SS "find_glob" .IX Subsection "find_glob" .Vb 1 \& $gv = $pmat\->find_glob( $name ) .Ve .PP Attempts to walk the symbol table looking for a symbol of the given name, returning the \f(CW\*(C`GLOB\*(C'\fR object if found. .SS "find_stash" .IX Subsection "find_stash" .Vb 1 \& $stash = $pmat\->find_stash( $name ) .Ve .PP Attempts to walk the symbol table looking for a stash of the given name. .SH "AUTHOR" .IX Header "AUTHOR" Paul Evans