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.020_081';
  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 then perl memory usage data will be written to a C<sizeme.db> file in the
 121 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.
 150
 151 Not accurate yet.
 152
 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