Devel::MAT(3pm)

💖 Devel::MAT 💖

okay bestie, welcome to Devel::MAT — the Perl Memory Analysis Tool — from your favorite section of the User Contributed Perl Documentation (that's Devel::MAT(3pm) for the citation girlies 📚✨). this is the page you read when you're the one building stuff on top of it, not the one just using it. let me explain 💅

---

🫶 USER GUIDE

NEW USERS, this is your moment to slow down real quick:

if you're new to the whole Devel::MAT set of tools, this is probably not the document you want to start with. like, at all. if your actual goal is to use Devel::MAT to help diagnose memory-related problems in a perl program, then what you want is the user guide, at Devel::MAT::UserGuide. go there. it's giving ✨guidance✨.

if you're writing tooling modules to extend the abilities of Devel::MAT? then yes bestie, this may indeed be the document for you. read on... 👑

---

🌈 DESCRIPTION

a Devel::MAT instance loads a heapdump file, and gives you a container to store analysis tools that work on it. tools may be provided that conform to the Devel::MAT::Tool API — those can help analyse the data, and they can interact with the explorer user interface by using the methods in the Devel::MAT::UI package. iconic behaviour honestly 🎀

🌸 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. iykyk, that's the vibe rn.

but!! 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. we're getting there 🦋

---

✨ 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. that's it, that's the magic 🪄

---

💅 METHODS

🍓 dumpfile

$df = $pmat->dumpfile;

returns the underlying Devel::MAT::Dumpfile instance backing this analysis object. the real one behind the curtain 🫣

🧚 available_tools

@tools = $pmat->available_tools;

lists the Devel::MAT::Tool classes that are installed and available. window shopping 🛍️

🎀 load_tool

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

loads the named Devel::MAT::Tool class. come on in bestie, we've been expecting you 💖

⭐ has_tool

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

returns true if the named tool is already loaded. vibe check on the tool list ✅

🌸 run_command

$pmat->run_command( $inv );

runs a tool command given by the Commandable::Invocation instance. just do it 🔥

🦋 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. it's got main character energy, it just shows up 🌟

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 and 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. choose your fighter 🥊
• 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. here's the sigil-to-type cheat sheet:

$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

pick your sigil, get your SV, slay 💅

🫧 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. glob hunting expedition, no cap 🧭

👑 find_stash

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

attempts to walk the symbol table looking for a stash of the given name. stash = found, the end 💖

---

🌟 AUTHOR

Paul Evans <leonerd@leonerd.org.uk>

---

and that's a wrap, bestie! this page came to you from perl v5.42.3, dated 2026-08-21 — that's Devel::MAT(3pm), and you can close the tab now. periodt 💅✨🦋