NAME

Devel::SizeMe - Extension for extracting detailed memory usage information

SYNOPSIS

Manual usage:

  use Devel::SizeMe qw(total_size perl_size);

  my $total_size = total_size( $ref_to_data );

  my $perl_size = perl_size();

Quick automatic usage:

    perl -d:SizeMe ...

DESCRIPTION

NOTE: This is all rather alpha and anything may change.

The functions traverse memory structures and return the total memory size in bytes. See Devel::Size for more information.

If the SIZEME env var is set then the functions also stream out detailed information about the individual data structures. This data can be written to a file or piped to a program for further processing.

If SIZEME env var is set to an empty string then all the *_size functions dump a textual representation of the memory data to stderr.

If SIZEME 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. See sizeme_store.pl.

If SIZEME 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 sizeme_store.pl script can be used to process the raw memory data. Typically run via the SIZEME env var. For example:

    export SIZEME='|./sizeme_store.pl --text'
    export SIZEME='|./sizeme_store.pl --dot=sizeme.dot'
    export SIZEME='|./sizeme_store.pl --db=sizeme.db'

The --text output is similar to the textual representation output by the module when the SIZEME 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:

  SIZEME='|sizeme_store.pl --db=sizeme.db' perl -MDevel::SizeMe=:all -e 'total_size(sub { })'

The sizeme_graph.pl script is a Mojolicious::Lite application that serves data to an interactive treemap visualization of the memory use. It can be run as:

    sizeme_graph.pl daemon

and then open http://127.0.0.1:3000

Please report bugs to:

    http://rt.cpan.org/NoAuth/Bugs.html?Dist=Devel-SizeMe

Automatic Mode

If loaded using the perl -d option (i.e., perl -d:SizeMe ...) and it's the first module loaded then perl memory usage data will be written to a sizeme.db file in the current directory when the script ends.

FUNCTIONS

size

    $size_in_bytes = size( $ref_to_data );

Measures and returns the size of the referenced data, without including any other data referenced by it.

total_size

    $size_in_bytes = total_size( $ref_to_data );

Like </size> but does include referenced data.

perl_size

    $size_in_bytes = perl_size();

Measures and returns the size of the entire perl interpreter. This is similar to calling total_size( \%main:: ) but also includes all the perl internals.

heap_size

    $size_in_bytes = heap_size();

Measures and returns the size of the entire process heap space, with nodes within that representing things like free space within malloc (if the malloc implementation can report that).

The goal here is for the returned 'total heap size' to be taken directly from the operating system and for a subnode called "unknown" to 'contain' the difference between everything we can measure and the total heap size reported by the operating system.

Far from accurate yet.

GETTING HELP

There's an #sizeme IRC channel on irc.perl.org and the devel-size@googlegroups.com mailing list (also at https://groups.google.com/d/forum/devel-size)

CONTRIBUTING

The source code is at https://github.com/timbunce/devel-sizeme

COPYRIGHT

Copyright (C) 2005 Dan Sugalski, Copyright (C) 2007-2008 Tels, Copyright (C) 2008 BrowserUK, Copyright (C) 2011-2012 Nicholas Clark, Copyright (C) 2012-2013 Tim Bunce.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl v5.8.8.

SEE ALSO

sizeme_store.pl, sizeme_graph.pl, perl(1), Devel::Size.