README

   1 =pod
   2
   3 Devel::Memory - Perl extension for finding the memory usage of Perl variables
   4
   5 =head1 SYNOPSIS
   6
   7   use Devel::Memory qw(size total_size);
   8
   9   my $size = size("A string");
  10   my @foo = (1, 2, 3, 4, 5);
  11   my $other_size = size(\@foo);
  12   my $total_size = total_size( $ref_to_data );
  13
  14 =head1 DESCRIPTION
  15
  16 Acts like Devel::Size 0.77 is the PERL_DMEM env var is not set.
  17
  18 Except that it also provides perl_size() and heap_size() functions.
  19
  20 If PERL_DMEM env var is set to an empty string then all the *_size functions
  21 dump a textual representation of the memory data to stderr.
  22
  23 If PERL_DMEM env var is set to a string that starts with "|" then the
  24 remainder of the string is taken to be a command name and popen() is used to
  25 start the command and the raw memory data is piped to it.
  26
  27 If PERL_DMEM env var is set to anything else it is treated as the name of a
  28 file the raw memory data should be written to.
  29
  30 The dmemtree.pl script can be used to process the raw memory data.
  31 Typically run via the PERL_DMEM env var. For example:
  32
  33     export PERL_DMEM='|./dmemtree.pl --text'
  34     export PERL_DMEM='|./dmemtree.pl --dot=dmemtree.dot'
  35     export PERL_DMEM='|./dmemtree.pl --db=dmemtree.db'
  36
  37 The --text output is similar to the textual representation output by the module
  38 when the PERL_DMEM env var is set to an empty string.
  39
  40 The --dot output is suitable for feeding to Graphviz.
  41
  42 The --db output is a SQLite database. (Very subject to change.)
  43
  44 Example usage:
  45
  46   PERL_DMEM='|./dmemtree.pl --db=dmemtree.db' perl -MDevel::Size=:all -e 'total_size(sub { })'
  47
  48 The dmemview.pl script is a Mojolicious::Lite application that serves data to
  49 an interactive treemap visualization of the memory use. It can be run as:
  50
  51     dmemview.pl daemon
  52
  53 and then open http://127.0.0.1:3000
  54
  55
  56 =head1 Build and Install
  57
  58 To build and install this module, you need:
  59
  60      Perl
  61      a working C or C++ compiler
  62      a make (or namke on Windows) utility
  63
  64 Follow these steps:
  65
  66 On Linux, Cygwin, or Unix:
  67
  68     perl Makefile.PL
  69     make
  70     make test
  71     sudo make install
  72
  73 On Windows:
  74
  75     perl Makefile.PL
  76     nmake
  77     nmake test
  78     nmake install
  79
  80 =head1 BUGREPORTS
  81
  82 Please report bugs to:
  83
  84     http://rt.cpan.org/NoAuth/Bugs.html?Dist=Devel-Memory
  85
  86 =head1 COPYRIGHT
  87
  88 Copyright (C) 2005 Dan Sugalski, Copyright (C) 2007-2008 Tels,
  89 Copyright (C) 2011-2012 Nicholas Clark, Copyright 2012 (C) Tim Bunce.
  90
  91 This module is free software; you can redistribute it and/or modify it
  92 under the same terms as Perl v5.8.8.
  93
  94 =cut