Mega rename to Devel::Memory commit

[p5sagit/Devel-Size.git] / lib / Devel / Memory.pm

diff --git a/lib/Devel/Memory.pm b/lib/Devel/Memory.pm
new file mode 100644 (file)
index 0000000..6572deb
--- /dev/null
+++ b/lib/Devel/Memory.pm
@@ -0,0 +1,100 @@
+package Devel::Memory;
+
+use strict;
+use vars qw($VERSION @ISA @EXPORT_OK %EXPORT_TAGS $warn $dangle);
+
+require 5.005;
+require Exporter;
+require XSLoader;
+
+@ISA = qw(Exporter);
+
+@EXPORT_OK = qw(size total_size perl_size);
+
+# This allows declaration   use Devel::Memory ':all';
+%EXPORT_TAGS = ( 'all' => \@EXPORT_OK );
+
+$VERSION = '0.01';
+
+XSLoader::load( __PACKAGE__);
+
+$warn = 1;
+$dangle = 0; ## Set true to enable warnings about dangling pointers
+
+1;
+__END__
+
+=pod
+
+Devel::Memory - Perl extension for finding the memory usage of Perl variables
+
+=head1 SYNOPSIS
+
+  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 $total_size = total_size( $ref_to_data );
+
+=head1 DESCRIPTION
+
+Acts like Devel::Size 0.77 if 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::Memory=: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
+
+Please report bugs to:
+
+    http://rt.cpan.org/NoAuth/Bugs.html?Dist=Devel-Memory
+
+=head1 COPYRIGHT
+
+Copyright (C) 2005 Dan Sugalski,
+Copyright (C) 2007-2008 Tels,
+Copyright (C) BrowserUK 2008,
+Copyright (C) 2011-2012 Nicholas Clark,
+Copyright (C) 2012 Tim Bunce.
+
+This module is free software; you can redistribute it and/or modify it
+under the same terms as Perl v5.8.8.
+
+=head1 SEE ALSO
+
+perl(1), L<Devel::Size>.
+
+=cut