lib/Devel/SizeMe.pm

   1 package Devel::SizeMe;
   2
   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 {
   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;
  13             ;
  14         $do_size_at_end = 1;
  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         }
  20     }
  21 }
  22
  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
  30 $VERSION = '0.03';
  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
  39 XSLoader::load( __PACKAGE__);
  40
  41 END {
  42     Devel::SizeMe::perl_size() if $do_size_at_end; # heap_size()
  43 }
  44
  45 1;
  46 __END__
  47
  48 =pod
  49
  50 Devel::SizeMe - Extension for extracting detailed memory usage information
  51
  52 =head1 SYNOPSIS
  53
  54 Manual usage:
  55
  56   use Devel::SizeMe qw(total_size perl_size);
  57
  58   my $total_size = total_size( $ref_to_data );
  59
  60   my $perl_size = perl_size();
  61
  62 Quick automatic usage:
  63
  64     perl -d:SizeMe ...
  65
  66 =head1 DESCRIPTION
  67
  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.
  72
  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.
  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.
  83 See L<sizeme_store.pl>.
  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
 117 =head2 Automatic Mode
 118
 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.
 122
 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, with nodes
 150 within that representing things like free space within malloc (if the malloc
 151 implementation can report that).
 152
 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.
 157
 158 Far from accurate yet.
 159
 160 =head1 COPYRIGHT
 161
 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.
 167
 168 This module is free software; you can redistribute it and/or modify it
 169 under the same terms as Perl v5.8.8.
 170
 171 =head1 SEE ALSO
 172
 173 L<sizeme_store.pl>, L<sizeme_graph.pl>, perl(1), L<Devel::Size>.
 174
 175 =cut