--- name: "Devel::MAT::Dumpfile" section: "3pm" platform: "linux" package: "libdevel-mat-perl" version: "0.53-1+b1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Devel::MAT::Dumpfile" --- # Devel::MAT::Dumpfile(3pm) load and analyse a heap dump file ## NAME "Devel::MAT::Dumpfile" - load and analyse a heap dump file ## SYNOPSIS ``` use Devel::MAT::Dumpfile; my $df = Devel::MAT::Dumpfile->load( "path/to/the/file.pmat" ); ``` ## DESCRIPTION This module provides a class that loads a heap dump file previously written by Devel::MAT::Dumper. It provides accessor methods to obtain various well-known root starting addresses, or to find arbitrary SVs by address. Each SV is represented by an instance of Devel::MAT::SV. ## CONSTRUCTOR ### load ``` $df = Devel::MAT::Dumpfile->load( $path, %args ); ``` Loads a heap dump file from the given path, and returns a new `"Devel::MAT::Dumpfile"` instance representing it. Takes the following named arguments: - progress =\> CODE If given, should be a CODE reference to a function that will be called regularly during the loading process, and given a status message to update the user. ## METHODS ### perlversion ``` $version = $df->perlversion; ``` Returns the version of perl that the heap dump file was created by, as a string in the form `5.14.2`. ### endian ``` $endian = $df->endian; ``` Returns the endian direction of the perl that the heap dump was created by, as either `"big"` or `"little"`. ### uint\_len ``` $len = $df->uint_len; ``` Returns the length in bytes of a uint field of the perl that the heap dump was created by. ### ptr\_len ``` $len = $df->ptr_len; ``` Returns the length in bytes of a pointer field of the perl that the heap dump was created by. ### nv\_len ``` $len = $df->nv_len; ``` Returns the length in bytes of a double field of the perl that the heap dump was created by. ### ithreads ``` $ithreads = $df->ithreads; ``` Returns a boolean indicating whether ithread support was enabled in the perl that the heap dump was created by. ### roots ``` %roots = $df->roots; ``` Returns a key/value pair list giving the names and SVs at each of the roots. ### roots\_strong ``` %roots = $df->roots_strong; ``` Returns a key/value pair list giving the names and SVs at each of the roots that count as strong references. ### roots\_weak ``` %roots = $df->roots_weak; ``` Returns a key/value pair list giving the names and SVs at each of the roots that count as strong references. ### ROOTS ``` $sv = $df->ROOT; ``` For each of the root names given below, a method exists with that name which returns the SV at that root: ``` main_cv defstash mainstack beginav checkav unitcheckav initav endav strtabhv envgv incgv statgv statname tmpsv defgv argvgv argvoutgv argvout_stack fdpidav preambleav modglobalhv regex_padav sortstash firstgv secondgv debstash stashcache isarev registered_mros ``` ### root\_descriptions ``` %rootdescs = $df->root_descriptions; ``` Returns a key/value pair list giving the (method) name and description text of each of the possible roots. ### root\_at ``` $addr = $df->root_at( $name ); ``` Returns the SV address of the given named root. ### root ``` $sv = $df->root( $name ); ``` Returns the given root SV. ### heap ``` @svs = $df->heap; ``` Returns all of the heap-allocated SVs, in no particular order ### stack ``` @svs = $df->stack; ``` Returns all the SVs on the stack ### contexts ``` @ctxs = $df->contexts; ``` Returns a list of Devel::MAT::Context objects representing the call context stack in the dumpfile. ### sv\_at ``` $sv = $df->sv_at( $addr ); ``` Returns the SV at the given address, or `"undef"` if one does not exist. (Note that this is unambiguous, as a Perl-level `"undef"` is represented by the immortal `"Devel::MAT::SV::UNDEF"` SV). ## AUTHOR Paul Evans \