Devel:...erGuide(3pm)

🦋 NAME 🦋

bestie, gather round: this is Devel::MAT::UserGuide — a users' introduction to Devel::MAT. It's a 3pm page from the User Contributed Perl Documentation, so yes it's perl-module-flavoured, and yes it still slaps. ✨

---

🌸 OVERVIEW 🌸

The Devel::MAT ecosystem lets developers of perl programs peek inside and analyse memory-related problems — think memory leaks, unexpected memory consumption, or just plain odd state. 👀

This is an "offline" analysis system, bestie. What that means: the analysis tools all run in a different process, possibly at a later time, than the perl process being analysed. No cap.

The basic workflow is two main stages:

1. A heap dump file gets generated from the perl process being debugged, at or around the time the problem becomes apparent. 📸
2. That file gets loaded by an analysis tool so you can inspect the contents. 🔍

These two stages are described separately here. Important note: they don't have to happen at the same time, on the same perl process, or even on the same sort of machine. It is fully possible to capture the heap from a process on, say, a small server, then copy the file to a development workstation or laptop and analyse it there later. That's exactly why the heap-dumping part, Devel::MAT::Dumper, is now separated into its own CPAN distribution — it can be installed on its own, without all the extra dependencies the full set of analysis tools require. iconic. 💅

---

💖 CAPTURING THE HEAP 💖

To generate the heap dump file that captures the contents of the heap, you use the Devel::MAT::Dumper module. Ultimately the dump function inside it needs to be called, but usually one of the module load options on the perl commandline can do it for you — no need to modify the running code. 🫶

For example, the -dump_at_DIE option means a heap dump gets written just before the process quits due to an uncaught exception:

$ perl -MDevel::MAT::Dumper=-dump_at_DIE program.pl

At this point the program starts up and runs normally, but if it's about to die, it first writes a .pmat file capturing the contents of the memory:

...
Dumping to program.pl.pmat because of DIE
Can't call method "method" on an undefined value at program.pl line 123.

There are a variety of other options for other situations, to suit other sorts of bugs and issues under investigation. For more options, see the documentation at IMPORT OPTIONS in Devel::MAT::Dumper. 📚

---

✨ ANALYSING THE HEAP ✨

Now that we have a .pmat file, we can load it and start inspecting the contents. A lot of the smaller, simpler tools are built as plugins for the main pmat command shell, so we can start by loading the heap file there:

$ pmat program.pl.pmat
Perl memory dumpfile from perl 5.24.1
Heap contains 15624 objects
pmat>

In this shell a whole collection of commands is available to help analyse and inspect the contents of memory represented by this heap dump — and you can use them interactively, narrowing down to find the cause of the memory issue. 🔥

It is hard in general to describe exactly what sequence of analysis commands will be best for finding the problem, because the specifics of each individual case call for different kinds of analysis and require us to ask different questions of the toolset. fr fr.

Ultimately there is quite a variety of possible underlying causes of memory growth in a Perl program. A few possible causes could be:

• A single large SV such as a hash or array containing millions of items, or a single string possibly gigabytes in length. 😳
• A large number of SVs being created and retained indefinitely, never being reclaimed.
• A large number of temporary SVs being created, but due to internal reference cycles their memory is never reclaimed despite them now being unreachable. 💀

This list of course is quite incomplete — there are as many different variations of erroneous memory usage as there are possible programs to write. Additionally, a lot of more interesting programs often suffer multiple overlapping issues at once. Nevertheless, this broad categorisation can help describe some overall approaches to finding memory usage issues.

A good first step to take in the pmat shell to try to distinguish these cases is to use the largest command. It requires no additional arguments, and by default it prints (in size order) the five largest individual SVs in the entire heap. 👑

pmat> largest

For more information about the largest command, see also largest in Devel::MAT::Tool::Sizes.

👑 One Large SV

Sometimes you'll find a single SV that far outweighs all the others; for example:

pmat> largest
SCALAR(PV) at 0x6a47708: 1.6 GiB
SCALAR(PV) at 0x1a59488: 4.0 MiB
HASH(0) at 0xfb4770=strtab: 1.5 MiB
SCALAR(PV) at 0x71b6468: 707.3 KiB
SCALAR(PV) at 0x71be2f0: 609.6 KiB
others: 46.2 MiB

In this output, we see that the topmost SV reported, at address 0x6a47708, is much larger than everything else put together. In this case we have essentially already found the cause of the memory usage growth, and we can proceed by identifying what this particular SV actually is, by following the process in Devel::MAT::UserGuide::IdentifyingAnSV. 🕵️‍♀️

For a brief overview, we can just count the total number of objects of various kinds in the heap:

pmat> count
  Kind       Count (blessed)        Bytes (blessed)
  ARRAY        182         0     16.0 KiB
  CODE         182         0     22.8 KiB
  GLOB         325         0     48.2 KiB
  ...

We can inspect the callstack at the time the heap dump was made:

pmat> callers
caller(0): CODE(PP) at 0x55555582a4e8=&main::__ANON__ => void
  at t/test.pl line 49
  $_[0]: SCALAR(PV) at 0x55c2bdce2778 = "arguments"
  $_[1]: SCALAR(PV) at 0x55c2bdce2868 = "go"
  $_[2]: SCALAR(PV) at 0x55c2bdce26e8 = "here"
...

---

🎀 COMMAND HELP 🎀

A list of the commands currently available in the shell can be found with the help command:

pmat> help
callers   - Display the caller stack
count     - Count the various kinds of SV
elems     - List the elements of an ARRAY SV
...

For more information about a particular command, just give its name as an argument to the help command:

pmat> help sizes
sizes - Summarize object and byte counts across different SV types

SYNOPSIS:
  sizes [OPTIONS...]

OPTIONS:
  --owned     sum SVs by owned size
  --struct    sum SVs by structural size

Also note that each command is implemented by a (correctly-cased) package under the Devel::MAT::Tool namespace. For example, the count tool is implemented by — and therefore more documentation can be found in — the Devel::MAT::Tool::Count package. 🌈

🫶 Specifying SVs

Many commands operate on a particular given SV. This can be specified in several ways:

• A numerical address directly:

pmat> show 0x55a7e4e59f78
IO()=IO::File at 0x55a7e4e59f78 with refcount 1
...

• A named root SV (see the roots command for a list of them all):

pmat> show defstash
STASH(61) at 0x55a7e4d69060=defstash with refcount 2

• A named symbol from the symbol table. Note that subs require the & sigil:

pmat> show $warnings::VERSION
SCALAR(PV) at 0x55a7e4d96550 with refcount 1
...

pmat> show &warnings::import
CODE(PP) at 0x55a7e4dc3458 with refcount 1
...

---

💜 AUTHOR 💜

Paul Evans <leonerd@leonerd.org.uk>

---

and that's a wrap, bestie!! 🎀 this whole vibe check came to you courtesy of perl v5.42.3, dated 2026-08-21, from the Devel:...erGuide(3pm) page itself. go forth and slay your memory leaks 💖🦋✨