Devel::MAT::UserGuide - a users' introduction to Devel::MAT
Devel::MAT::UserGuide
Devel::MAT
The Devel::MAT ecosystem allows developers of perl programs to inspect and analyse memory-related problems such as memory leaks, unexpected memory consumption, or odd state. This is an "offline" analysis system, in the sense that the analysis tools all run in a different process, possibly at a later time, than the perl process that is being analysed.
The basic workflow consists of two main stages: first a heap dump file is generated from the perl process being debugged, at or around the time that the problem becomes apparent, and secondly this file is loaded by an analysis tool in order to inspect the contents.
These two stages are described here separately. It is important to note that they don't have to be done 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 at a later time.
To generate the heap dump file that captures the contents of the heap, the Devel::MAT::Dumper module is used. Ultimately the dump function within it needs to be called, but usually one of the module load options can be used on the perl commandline to achieve this without requiring the running code to be modified.
dump
For example, the -dump_at_DIE option means that a heap dump will be written just before the process quits due to an uncaught exception:
-dump_at_DIE
$ perl -MDevel::MAT::Dumper=-dump_at_DIE program.pl
At this point, the program will start up and run normally, but if it is about to die, it will first write 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.
Now that we have a .pmat file, we can load it and start to inspect 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>
For a brief overview, we can just count the total number of objects of various kinds in the heap:
pmat> count Kind Count (blessed) ARRAY 1259 89 CODE 274 GLOB 326 ...
We can inspect the callstack at the time the heap dump was made:
pmat> callstack program.pl line 152: &main::func => void $_[0]: 'arguments' $_[1]: 'go' $_[2]: 'here' ...
For more information about a tool, for example the count tool, note that each one is implemented by a (correctly-cased) package under the Devel::MAT::Tool namespace. In this instance, the count tool is implemented by, and therefore more documentation can be found in, the Devel::MAT::Tool::Count package.
count
Devel::MAT::Tool
A list of the commands currently available in the shell can be found by
pmat> help
Paul Evans <leonerd@leonerd.org.uk>
To install Devel::MAT, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Devel::MAT
CPAN shell
perl -MCPAN -e shell install Devel::MAT
For more information on module installation, please visit the detailed CPAN module installation guide.