Count all stack frames, not just the used ones

[p5sagit/Devel-Size.git] / README

diff --git a/README b/README
index 9f99cf1..0bebcc8 100644 (file)
--- a/README
+++ b/README
@@ -1,59 +1,92 @@
 =pod
 
-Devel::Size - Perl extension for finding the memory usage of Perl variables
+Devel::Memory - Perl extension for finding the memory usage of Perl variables
 
 =head1 SYNOPSIS
 
-  use Devel::Size qw(size total_size);
+  use Devel::Memory qw(size total_size);
 
   my $size = size("A string");
-
   my @foo = (1, 2, 3, 4, 5);
   my $other_size = size(\@foo);
-
-  my $foo = {a => [1, 2, 3],
-         b => {a => [1, 3, 4]}
-         };
-  my $total_size = total_size($foo);
+  my $total_size = total_size( $ref_to_data );
 
 =head1 DESCRIPTION
 
-This module figures out the real size of Perl variables in bytes, as
-accurately as possible.
+Acts like Devel::Size 0.77 is the PERL_DMEM env var is not set.
+
+Except that it also provides perl_size() and heap_size() functions.
+
+If PERL_DMEM env var is set to an empty string then all the *_size functions
+dump a textual representation of the memory data to stderr.
+
+If PERL_DMEM env var is set to a string that starts with "|" then the
+remainder of the string is taken to be a command name and popen() is used to
+start the command and the raw memory data is piped to it.
+
+If PERL_DMEM env var is set to anything else it is treated as the name of a
+file the raw memory data should be written to.
+
+The dmemtree.pl script can be used to process the raw memory data.
+Typically run via the PERL_DMEM env var. For example:
+
+    export PERL_DMEM='|./dmemtree.pl --text'
+    export PERL_DMEM='|./dmemtree.pl --dot=dmemtree.dot'
+    export PERL_DMEM='|./dmemtree.pl --db=dmemtree.db'
+
+The --text output is similar to the textual representation output by the module
+when the PERL_DMEM env var is set to an empty string.
+
+The --dot output is suitable for feeding to Graphviz.
+
+The --db output is a SQLite database. (Very subject to change.)
+
+Example usage:
+
+  PERL_DMEM='|./dmemtree.pl --db=dmemtree.db' perl -MDevel::Size=:all -e 'total_size(sub { })'
+
+The dmemview.pl script is a Mojolicious::Lite application that serves data to
+an interactive treemap visualization of the memory use. It can be run as:
+
+    dmemview.pl daemon
+
+and then open http://127.0.0.1:3000
+
 
 =head1 Build and Install
 
 To build and install this module, you need:
 
-        Perl
-        a working C or C++ compiler
-        a make (or namke on Windows) utility
+     Perl
+     a working C or C++ compiler
+     a make (or namke on Windows) utility
 
 Follow these steps:
 
 On Linux, Cygwin, or Unix:
 
-       perl Makefile.PL
-       make
-       make test
-       sudo make install
-
+    perl Makefile.PL
+    make
+    make test
+    sudo make install
+    
 On Windows:
 
-       perl Makefile.PL
-       nmake
-       nmake test
-       nmake install
+    perl Makefile.PL
+    nmake
+    nmake test
+    nmake install
 
 =head1 BUGREPORTS
 
 Please report bugs to:
 
-       http://rt.cpan.org/NoAuth/Bugs.html?Dist=Devel-Size
+    http://rt.cpan.org/NoAuth/Bugs.html?Dist=Devel-Memory
 
 =head1 COPYRIGHT
 
-Copyright (C) 2005 Dan Sugalski, Copyright (C) 2007 Tels
+Copyright (C) 2005 Dan Sugalski, Copyright (C) 2007-2008 Tels,
+Copyright (C) 2011-2012 Nicholas Clark, Copyright 2012 (C) Tim Bunce.
 
 This module is free software; you can redistribute it and/or modify it
 under the same terms as Perl v5.8.8.