README

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