Commit | Line | Data |
0e977dbc |
1 | package Devel::SizeMe; |
2 | |
eda23e24 |
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 ..." |
6 | BEGIN { |
e988a695 |
7 | if ($^P and keys %INC == 1) { |
eda23e24 |
8 | warn "Note: Devel::SizeMe currently disables perl debugger mode\n"; |
eda23e24 |
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; |
13 | ; |
14 | $do_size_at_end = 1; |
01f5c6f5 |
15 | |
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}; |
19 | } |
eda23e24 |
20 | } |
0e977dbc |
21 | } |
22 | |
eda23e24 |
23 | use strict; |
24 | use vars qw($VERSION @ISA @EXPORT_OK %EXPORT_TAGS $warn $dangle); |
25 | |
26 | require 5.005; |
27 | require Exporter; |
28 | require XSLoader; |
29 | |
90600dae |
30 | $VERSION = '0.020_082'; |
eda23e24 |
31 | @ISA = qw(Exporter); |
32 | |
33 | @EXPORT_OK = qw(size total_size perl_size heap_size); |
34 | %EXPORT_TAGS = ( 'all' => \@EXPORT_OK ); # for use Devel::SizeMe ':all'; |
35 | |
36 | $warn = 1; |
37 | $dangle = 0; ## Set true to enable warnings about dangling pointers |
38 | |
eda23e24 |
39 | XSLoader::load( __PACKAGE__); |
40 | |
0e977dbc |
41 | END { |
12ae883b |
42 | Devel::SizeMe::perl_size() if $do_size_at_end; # heap_size() |
0e977dbc |
43 | } |
44 | |
45 | 1; |
eda23e24 |
46 | __END__ |
47 | |
48 | =pod |
49 | |
12ae883b |
50 | Devel::SizeMe - Extension for extracting detailed memory usage information |
eda23e24 |
51 | |
52 | =head1 SYNOPSIS |
53 | |
12ae883b |
54 | Manual usage: |
55 | |
56 | use Devel::SizeMe qw(total_size perl_size); |
eda23e24 |
57 | |
eda23e24 |
58 | my $total_size = total_size( $ref_to_data ); |
59 | |
12ae883b |
60 | my $perl_size = perl_size(); |
61 | |
62 | Quick automatic usage: |
63 | |
64 | perl -d:SizeMe ... |
65 | |
eda23e24 |
66 | =head1 DESCRIPTION |
67 | |
12ae883b |
68 | NOTE: This is all rather alpha and anything may change. |
69 | |
70 | The functions traverse memory structures and return the total memory size in |
71 | bytes. See L<Devel::Size> for more information. |
eda23e24 |
72 | |
12ae883b |
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. |
eda23e24 |
76 | |
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. |
79 | |
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. |
12ae883b |
83 | See L<sizeme_store.pl>. |
eda23e24 |
84 | |
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. |
87 | |
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: |
90 | |
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' |
94 | |
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. |
97 | |
98 | The --dot output is suitable for feeding to Graphviz. |
99 | |
100 | The --db output is a SQLite database. (Very subject to change.) |
101 | |
102 | Example usage: |
103 | |
104 | SIZEME='|sizeme_store.pl --db=sizeme.db' perl -MDevel::SizeMe=:all -e 'total_size(sub { })' |
105 | |
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: |
108 | |
109 | sizeme_graph.pl daemon |
110 | |
111 | and then open http://127.0.0.1:3000 |
112 | |
113 | Please report bugs to: |
114 | |
115 | http://rt.cpan.org/NoAuth/Bugs.html?Dist=Devel-SizeMe |
116 | |
12ae883b |
117 | =head2 Automatic Mode |
118 | |
119 | If loaded using the perl C<-d> option (i.e., C<perl -d:SizeMe ...>) |
120 | then perl memory usage data will be written to a C<sizeme.db> file in the |
121 | current directory when the script ends. |
122 | |
4283dcb8 |
123 | =head1 FUNCTIONS |
124 | |
125 | =head2 size |
126 | |
127 | $size_in_bytes = size( $ref_to_data ); |
128 | |
129 | Measures and returns the size of the referenced data, without including any |
130 | other data referenced by it. |
131 | |
132 | =head2 total_size |
133 | |
134 | $size_in_bytes = total_size( $ref_to_data ); |
135 | |
136 | Like </size> but does include referenced data. |
137 | |
138 | =head2 perl_size |
139 | |
140 | $size_in_bytes = perl_size(); |
141 | |
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. |
144 | |
145 | =head2 heap_size |
146 | |
147 | $size_in_bytes = heap_size(); |
148 | |
149 | Measures and returns the size of the entire process heap space. |
150 | |
151 | Not accurate yet. |
152 | |
eda23e24 |
153 | =head1 COPYRIGHT |
154 | |
155 | Copyright (C) 2005 Dan Sugalski, |
156 | Copyright (C) 2007-2008 Tels, |
157 | Copyright (C) 2008 BrowserUK, |
158 | Copyright (C) 2011-2012 Nicholas Clark, |
159 | Copyright (C) 2012 Tim Bunce. |
160 | |
161 | This module is free software; you can redistribute it and/or modify it |
162 | under the same terms as Perl v5.8.8. |
163 | |
164 | =head1 SEE ALSO |
165 | |
166 | perl(1), L<Devel::Size>. |
167 | |
168 | =cut |