Debian Codegraph @

README

raw
1 NAME
2
3 Devel::MAT::Dumper - write a heap dump file for later analysis
4
5 SYNOPSIS
6
7 use Devel::MAT::Dumper;
8
9 Devel::MAT::Dumper::dump( "path/to/the/file.pmat" );
10
11 DESCRIPTION
12
13 This module provides the memory-dumping function that creates a heap
14 dump file which can later be read by Devel::MAT::Dumpfile. It provides
15 a single function which is not exported, which writes a file to the
16 given path.
17
18 The dump file will contain a representation of every SV in Perl's
19 arena, providing information about pointers between them, as well as
20 other information about the state of the process at the time it was
21 created. It contains a snapshot of the process at that moment in time,
22 which can later be loaded and analysed by various tools using
23 Devel::MAT::Dumpfile.
24
25 This module used to be part of the main Devel::MAT distribution but is
26 now in its own one so that it can be installed independently on servers
27 or other locations where perl processes need to inspected but analysis
28 tools can be run elsewhere.
29
30 IMPORT OPTIONS
31
32 The following import options control the behaviour of the module. They
33 may primarily be useful when used in the -M perl option:
34
35 -dump_at_DIE
36
37 Installs a handler for the special __DIE__ signal to write a dump file
38 when die() is about to cause a fatal signal. This is more reliable at
39 catching the callstack and memory state than using an END block.
40
41 $ perl -MDevel::MAT::Dumper=-dump_at_DIE ...
42
43 -dump_at_WARN
44
45 Installs a handler for the special __WARN__ signal to write a dump file
46 when perl prints a warning.
47
48 $ perl -MDevel::MAT::Dumper=-dump_at_WARN ...
49
50 It is likely useful to combine this with the NNN numbering feature of
51 the -file argument, to ensure that later warnings don't overwrite a
52 particular file.
53
54 -dump_at_END
55
56 Installs an END block which writes a dump file at END time, just before
57 the interpreter exits.
58
59 $ perl -MDevel::MAT::Dumper=-dump_at_END ...
60
61 -dump_at_SIGQUIT
62
63 Installs a handler for SIGQUIT to write a dump file if the signal is
64 received. The signal handler will remain in place and can be used
65 several times.
66
67 $ perl -MDevel::MAT::Dumper=-dump_at_SIGQUIT ...
68
69 Take care if you are using the <Ctrl-\> key combination on a terminal
70 to send this signal to a foreground process, because if it has fork()ed
71 any background workers or similar, the signal will also be delivered to
72 those as well.
73
74 -dump_at_SIGNAME
75
76 Installs a handler for the named signal (e.g. SIGABRT, SIGINT) to write
77 a dump file if the signal is received. After dumping the file, the
78 signal handler is removed and the signal re-raised.
79
80 $ perl -MDevel::MAT::Dumper=-dump_at_SIGABRT ...
81
82 Note that SIGABRT uses an "unsafe" signal handler (i.e. not deferred
83 until the next perl op), so it can capture the full context of any
84 ongoing XS or C library operations.
85
86 -file $PATH
87
88 Sets the name of the file which is automatically dumped; defaults to
89 basename $0.pmat if not supplied.
90
91 $ perl -MDevel::MAT::Dumper=-file,foo.pmat ...
92
93 In the special case that $0 is exactly the string -e or -E, the
94 filename will be prefixed with perl so as not to create files whose
95 names begin with a leading hyphen, as this confuses some commandline
96 parsers.
97
98 $ perl -MDevel::MAT::Dumper=-dump_at_END -E 'say "hello"'
99 hello
100 Dumping to perl-e.pmat because of END
101
102 If the pattern contains NNN, this will be replaced by a unique serial
103 number per written file, starting from 0. This may be helpful in the
104 case of DIE, WARN or SIGQUIT handlers, which could be invoked multiple
105 times.
106
107 The file name is converted to an absolute path immediately, so if the
108 running program later calls chdir(), it will still be generated in the
109 directory the program started from rather than the one it happens to be
110 in at the time.
111
112 -max_string
113
114 Sets the maximum length of string buffer to dump from PVs; defaults to
115 256 if not supplied. Use a negative size to dump the entire buffer of
116 every PV regardless of size.
117
118 -eager_open
119
120 Opens the dump file immediately at import time, instead of waiting
121 until the time it actually writes the heap dump. This may be useful if
122 the process changes user ID, or to debug problems involving too many
123 open filehandles.
124
125 FUNCTIONS
126
127 These functions are not exported, they must be called fully-qualified.
128
129 dump
130
131 dump( $path );
132
133 Writes a heap dump to the named file
134
135 dumpfh
136
137 dumpfh( $fh );
138
139 Writes a heap dump to the given filehandle (which must be a plain
140 OS-level filehandle, though does not need to be a regular file, or
141 seekable).
142
143 AUTHOR
144
145 Paul Evans <[email protected]>
146