NAME

       "Devel::MAT::Dumper" - write a heap dump file for later analysis

SYNOPSIS

        use Devel::MAT::Dumper;

        Devel::MAT::Dumper::dump( "path/to/the/file.pmat" );

DESCRIPTION

       This module provides the memory-dumping function that creates a heap dump file which can
       later be read by Devel::MAT::Dumpfile. It provides a single function which is not
       exported, which writes a file to the given path.

       The dump file will contain a representation of every SV in Perl's arena, providing
       information about pointers between them, as well as other information about the state of
       the process at the time it was created. It contains a snapshot of the process at that
       moment in time, which can later be loaded and analysed by various tools using
       "Devel::MAT::Dumpfile".

       This module used to be part of the main Devel::MAT distribution but is now in its own one
       so that it can be installed independently on servers or other locations where perl
       processes need to inspected but analysis tools can be run elsewhere.

IMPORT OPTIONS

       The following "import" options control the behaviour of the module. They may primarily be
       useful when used in the "-M" perl option:

   -dump_at_DIE
       Installs a handler for the special "__DIE__" signal to write a dump file when "die()" is
       about to cause a fatal signal. This is more reliable at catching the callstack and memory
       state than using an "END" block.

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

   -dump_at_WARN
       Installs a handler for the special "__WARN__" signal to write a dump file when perl prints
       a warning.

          $ perl -MDevel::MAT::Dumper=-dump_at_WARN ...

       It is likely useful to combine this with the "NNN" numbering feature of the "-file"
       argument, to ensure that later warnings don't overwrite a particular file.

   -dump_at_END
       Installs an "END" block which writes a dump file at "END" time, just before the
       interpreter exits.

          $ perl -MDevel::MAT::Dumper=-dump_at_END ...

   -dump_at_SIGQUIT
       Installs a handler for "SIGQUIT" to write a dump file if the signal is received. The
       signal handler will remain in place and can be used several times.

          $ perl -MDevel::MAT::Dumper=-dump_at_SIGQUIT ...

       Take care if you are using the "<Ctrl-\>" key combination on a terminal to send this
       signal to a foreground process, because if it has "fork()"ed any background workers or
       similar, the signal will also be delivered to those as well.

   -dump_at_SIGNAME
       Installs a handler for the named signal (e.g. "SIGABRT", "SIGINT") to write a dump file if
       the signal is received. After dumping the file, the signal handler is removed and the
       signal re-raised.

          $ perl -MDevel::MAT::Dumper=-dump_at_SIGABRT ...

       Note that "SIGABRT" uses an "unsafe" signal handler (i.e. not deferred until the next perl
       op), so it can capture the full context of any ongoing XS or C library operations.

   -file $PATH
       Sets the name of the file which is automatically dumped; defaults to basename $0.pmat if
       not supplied.

          $ perl -MDevel::MAT::Dumper=-file,foo.pmat ...

       In the special case that $0 is exactly the string "-e" or "-E", the filename will be
       prefixed with "perl" so as not to create files whose names begin with a leading hyphen, as
       this confuses some commandline parsers.

          $ perl -MDevel::MAT::Dumper=-dump_at_END -E 'say "hello"'
          hello
          Dumping to perl-e.pmat because of END

       If the pattern contains "NNN", this will be replaced by a unique serial number per written
       file, starting from 0. This may be helpful in the case of "DIE", "WARN" or "SIGQUIT"
       handlers, which could be invoked multiple times.

       The file name is converted to an absolute path immediately, so if the running program
       later calls "chdir()", it will still be generated in the directory the program started
       from rather than the one it happens to be in at the time.

   -max_string
       Sets the maximum length of string buffer to dump from PVs; defaults to 256 if not
       supplied. Use a negative size to dump the entire buffer of every PV regardless of size.

   -eager_open
       Opens the dump file immediately at "import" time, instead of waiting until the time it
       actually writes the heap dump. This may be useful if the process changes user ID, or to
       debug problems involving too many open filehandles.

FUNCTIONS

       These functions are not exported, they must be called fully-qualified.

   dump
          dump( $path )

       Writes a heap dump to the named file

   dumpfh
          dumpfh( $fh )

       Writes a heap dump to the given filehandle (which must be a plain OS-level filehandle,
       though does not need to be a regular file, or seekable).

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>