3 # As a handy convenience, make perl -d:SizeMe automatically call heap_size
4 # in an END block, and also set some $^P flags to get more detail.
5 my $do_size_at_end; # set true below for "perl -d:SizeMe ..."
7 if ($^P and keys %INC == 1) {
8 warn "Note: Devel::SizeMe currently disables perl debugger mode\n";
9 # default $^P set by "perl -d" is 0x73f
10 $^P = 0x10 # Keep info about source lines on which a sub is defined
11 | 0x100 # Provide informative "file" names for evals
12 | 0x200 # Provide informative names to anonymous subroutines;
16 if (not defined $ENV{SIZEME}) {
17 $ENV{SIZEME} = "| sizeme_store.pl --db=sizeme.db";
18 warn qq{SIZEME env var not set, defaulting to "$ENV{SIZEME}"\n};
24 use vars qw($VERSION @ISA @EXPORT_OK %EXPORT_TAGS $warn $dangle);
33 @EXPORT_OK = qw(size total_size perl_size heap_size);
34 %EXPORT_TAGS = ( 'all' => \@EXPORT_OK ); # for use Devel::SizeMe ':all';
37 $dangle = 0; ## Set true to enable warnings about dangling pointers
39 XSLoader::load( __PACKAGE__);
42 Devel::SizeMe::perl_size() if $do_size_at_end; # heap_size()
50 Devel::SizeMe - Extension for extracting detailed memory usage information
56 use Devel::SizeMe qw(total_size perl_size);
58 my $total_size = total_size( $ref_to_data );
60 my $perl_size = perl_size();
62 Quick automatic usage:
68 NOTE: This is all rather alpha and anything may change.
70 The functions traverse memory structures and return the total memory size in
71 bytes. See L<Devel::Size> for more information.
73 If the C<SIZEME> env var is set then the functions also stream out detailed
74 information about the individual data structures. This data can be written to a
75 file or piped to a program for further processing.
77 If SIZEME env var is set to an empty string then all the *_size functions
78 dump a textual representation of the memory data to stderr.
80 If SIZEME env var is set to a string that starts with "|" then the
81 remainder of the string is taken to be a command name and popen() is used to
82 start the command and the raw memory data is piped to it.
83 See L<sizeme_store.pl>.
85 If SIZEME env var is set to anything else it is treated as the name of a
86 file the raw memory data should be written to.
88 The sizeme_store.pl script can be used to process the raw memory data.
89 Typically run via the SIZEME env var. For example:
91 export SIZEME='|./sizeme_store.pl --text'
92 export SIZEME='|./sizeme_store.pl --dot=sizeme.dot'
93 export SIZEME='|./sizeme_store.pl --db=sizeme.db'
95 The --text output is similar to the textual representation output by the module
96 when the SIZEME env var is set to an empty string.
98 The --dot output is suitable for feeding to Graphviz.
100 The --db output is a SQLite database. (Very subject to change.)
104 SIZEME='|sizeme_store.pl --db=sizeme.db' perl -MDevel::SizeMe=:all -e 'total_size(sub { })'
106 The sizeme_graph.pl script is a Mojolicious::Lite application that serves data to
107 an interactive treemap visualization of the memory use. It can be run as:
109 sizeme_graph.pl daemon
111 and then open http://127.0.0.1:3000
113 Please report bugs to:
115 http://rt.cpan.org/NoAuth/Bugs.html?Dist=Devel-SizeMe
117 =head2 Automatic Mode
119 If loaded using the perl C<-d> option (i.e., C<perl -d:SizeMe ...>)
120 and it's the first module loaded then perl memory usage data will be written to
121 a C<sizeme.db> file in the current directory when the script ends.
127 $size_in_bytes = size( $ref_to_data );
129 Measures and returns the size of the referenced data, without including any
130 other data referenced by it.
134 $size_in_bytes = total_size( $ref_to_data );
136 Like </size> but does include referenced data.
140 $size_in_bytes = perl_size();
142 Measures and returns the size of the entire perl interpreter. This is similar
143 to calling C<total_size( \%main:: )> but also includes all the perl internals.
147 $size_in_bytes = heap_size();
149 Measures and returns the size of the entire process heap space, with nodes
150 within that representing things like free space within malloc (if the malloc
151 implementation can report that).
153 The goal here is for the returned 'total heap size' to be taken directly from
154 the operating system and for a subnode called "unknown" to 'contain' the
155 difference between everything we can measure and the total heap size reported
156 by the operating system.
158 Far from accurate yet.
162 Copyright (C) 2005 Dan Sugalski,
163 Copyright (C) 2007-2008 Tels,
164 Copyright (C) 2008 BrowserUK,
165 Copyright (C) 2011-2012 Nicholas Clark,
166 Copyright (C) 2012 Tim Bunce.
168 This module is free software; you can redistribute it and/or modify it
169 under the same terms as Perl v5.8.8.
173 L<sizeme_store.pl>, L<sizeme_graph.pl>, perl(1), L<Devel::Size>.