README

   1
   2
   3 =pod
   4
   5 Devel::SizeMe - Perl extension for finding the memory usage of Perl variables
   6
   7 =head1 SYNOPSIS
   8
   9   use Devel::SizeMe qw(size total_size);
  10
  11   my $size = size("A string");
  12   my @foo = (1, 2, 3, 4, 5);
  13   my $other_size = size(\@foo);
  14   my $total_size = total_size( $ref_to_data );
  15
  16 =head1 DESCRIPTION
  17
  18 Acts like Devel::Size 0.77 is the PERL_DMEM env var is not set.
  19
  20 Except that it also provides perl_size() and heap_size() functions.
  21
  22 If PERL_DMEM env var is set to an empty string then all the *_size functions
  23 dump a textual representation of the memory data to stderr.
  24
  25 If PERL_DMEM env var is set to a string that starts with "|" then the
  26 remainder of the string is taken to be a command name and popen() is used to
  27 start the command and the raw memory data is piped to it.
  28
  29 If PERL_DMEM env var is set to anything else it is treated as the name of a
  30 file the raw memory data should be written to.
  31
  32 The dmemtree.pl script can be used to process the raw memory data.
  33 Typically run via the PERL_DMEM env var. For example:
  34
  35     export PERL_DMEM='|./dmemtree.pl --text'
  36     export PERL_DMEM='|./dmemtree.pl --dot=dmemtree.dot'
  37     export PERL_DMEM='|./dmemtree.pl --db=dmemtree.db'
  38
  39 The --text output is similar to the textual representation output by the module
  40 when the PERL_DMEM env var is set to an empty string.
  41
  42 The --dot output is suitable for feeding to Graphviz.
  43
  44 The --db output is a SQLite database. (Very subject to change.)
  45
  46 Example usage:
  47
  48   PERL_DMEM='|./dmemtree.pl --db=dmemtree.db' perl -MDevel::Size=:all -e 'total_size(sub { })'
  49
  50 The dmemview.pl script is a Mojolicious::Lite application that serves data to
  51 an interactive treemap visualization of the memory use. It can be run as:
  52
  53     dmemview.pl daemon
  54
  55 and then open http://127.0.0.1:3000
  56
  57
  58 =head1 Build and Install
  59
  60 To build and install this module, you need:
  61
  62      Perl
  63      a working C or C++ compiler
  64      a make (or namke on Windows) utility
  65
  66 Follow these steps:
  67
  68 On Linux, Cygwin, or Unix:
  69
  70     perl Makefile.PL
  71     make
  72     make test
  73     sudo make install
  74
  75 On Windows:
  76
  77     perl Makefile.PL
  78     nmake
  79     nmake test
  80     nmake install
  81
  82 =head1 BUGREPORTS
  83
  84 Please report bugs to:
  85
  86     http://rt.cpan.org/NoAuth/Bugs.html?Dist=Devel-SizeMe
  87
  88 =head1 COPYRIGHT
  89
  90 Copyright (C) 2005 Dan Sugalski,
  91 Copyright (C) 2007-2008 Tels,
  92 Copyright (C) 2008 BrowserUK,
  93 Copyright (C) 2011-2012 Nicholas Clark,
  94 Copyright (C) 2012 Tim Bunce.
  95
  96 This module is free software; you can redistribute it and/or modify it
  97 under the same terms as Perl v5.8.8.
  98
  99 =head1 TODO
 100
 101 Random notes...
 102
 103 Refactoring:
 104
 105     Devel::SizeMe::Core - loads XS and sets options
 106     Devel::SizeMe - loads Devel::SizeMe::Core
 107         -d:SizeMe=opts?
 108     Devel::SizeMe::Stream - parse raw stream
 109     Devel::SizeMe::Store - db write
 110     Devel::SizeMe::Data - db read / orlite?
 111     Devel::SizeMe::Graph - data reading/processing for sizeme_graph
 112     sizeme_store - script wrapper for Devel::SizeMe::Store
 113     sizeme_graph - Mojolicious app wrapper using Devel::SizeMe::Graph
 114     tests!
 115     Support multiple runs to same sizeme_store process, generating separate files
 116     Name runs to allow total_size (for example) of multiple data structures
 117
 118 Issues:
 119
 120     two cases where PERL_SUBVERSION is checked with a plain || (marked XXX)
 121
 122 Future
 123
 124
 125     Add addr to leaf to enable visualization of memory layout
 126
 127     Add token for ptr to node already seen (identified by addr I presume)
 128         so we can move from a Tree to a DAG and see alternative name paths
 129         and reference loops
 130
 131 =cut