From: Tim Bunce Date: Tue, 2 Oct 2012 19:28:35 +0000 (+0100) Subject: More docs and other polish for release. X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=12ae883b8d14ae6641e94ab8bf56222c26291985;p=p5sagit%2FDevel-Size.git More docs and other polish for release. --- diff --git a/CHANGES b/CHANGES index 95b893e..2aabe3c 100644 --- a/CHANGES +++ b/CHANGES @@ -1,9 +1,10 @@ -Revision history for Perl extension Devel::Memory. +Revision history for Perl extension Devel::SizeMe. 0.02 2012-10-02 Tim Bunce * Renamed to Devel::SizeMe. * Assorted fixes, cleanups and polish. + * Greatly extended perl_size coverage thanks to rafl. 0.01 2012-09-29 Tim Bunce diff --git a/README b/README index d8a3a0e..0500042 100644 --- a/README +++ b/README @@ -1,26 +1,3 @@ -TODO - - Devel::SizeMe::Core - loads XS and sets options - Devel::SizeMe - loads XS - -d:SizeMe=opts - Devel::SizeMe::Stream - parse raw stream - Devel::SizeMe::Store - db write - Devel::SizeMe::Data - db read / orlite? - Devel::SizeMe::Graph - data reading/processing for sizeme_graph - sizeme_store - script wrapper for Devel::SizeMe::Store - sizeme_graph - Mojolicious app wrapper using Devel::SizeMe::Graph - tests - Support multiple runs to same sizeme_store process, generating separate files - Name runs to allow total_size (for example) of multiple data structures - -Issues: - two cases where PERL_SUBVERSION is check with a plain || (marked XXX) -Optimizations: - Remove depth from stream? -Future - Add addr to leaf to visualize memory layout - Add token for ptr to node already seen (identified by addr I presume) - so we can move from a Tree to a DAG and see alternative name paths. =pod @@ -119,4 +96,36 @@ 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 TODO + +Random notes... + +Refactoring: + + Devel::SizeMe::Core - loads XS and sets options + Devel::SizeMe - loads Devel::SizeMe::Core + -d:SizeMe=opts? + Devel::SizeMe::Stream - parse raw stream + Devel::SizeMe::Store - db write + Devel::SizeMe::Data - db read / orlite? + Devel::SizeMe::Graph - data reading/processing for sizeme_graph + sizeme_store - script wrapper for Devel::SizeMe::Store + sizeme_graph - Mojolicious app wrapper using Devel::SizeMe::Graph + tests! + Support multiple runs to same sizeme_store process, generating separate files + Name runs to allow total_size (for example) of multiple data structures + +Issues: + + two cases where PERL_SUBVERSION is checked with a plain || (marked XXX) + +Future + + + Add addr to leaf to enable visualization of memory layout + + Add token for ptr to node already seen (identified by addr I presume) + so we can move from a Tree to a DAG and see alternative name paths + and reference loops + =cut diff --git a/SizeMe.xs b/SizeMe.xs index 87f1041..6914a7f 100644 --- a/SizeMe.xs +++ b/SizeMe.xs @@ -1130,6 +1130,7 @@ sv_size(pTHX_ struct state *const st, pPATH, const SV * const orig_thing, if (AvMAX(thing) != -1) { /* an array with 10 slots has AvMax() set to 9 - te 2007-04-22 */ ADD_SIZE(st, "av_max", sizeof(SV *) * (AvMAX(thing) + 1)); + ADD_ATTR(st, NPattr_NOTE, "av_len", av_len((AV*)thing)); dbg_printf(("total_size: %li AvMAX: %li av_len: $i\n", st->total_size, AvMAX(thing), av_len((AV*)thing))); if (recurse >= st->min_recurse_threshold) { diff --git a/bin/sizeme_store.pl b/bin/sizeme_store.pl index 9a8d889..f6701d0 100755 --- a/bin/sizeme_store.pl +++ b/bin/sizeme_store.pl @@ -1,9 +1,37 @@ #!/usr/bin/env perl -# Read the raw memory data from Devel::Memory and process the tree -# (as a stack, propagating data such as totals, up the tree). -# Output completed nodes in the request formats. -# +=head1 NAME + +sizeme_store.pl - process and store the raw data stream from Devel::SizeMe + +=head1 SYNOPSIS + + sizeme_store.pl [--text] [--dot=sizeme.dot] [--db=sizeme.db] + +Typically used via the C env var: + + export SIZEME='|./sizeme_store.pl --text' + export SIZEME='|./sizeme_store.pl --dot=sizeme.dot' + export SIZEME='|./sizeme_store.pl --db=sizeme.db' + +=head1 DESCRIPTION + +Reads the raw memory data from Devel::SizeMe and processes the tree +via a stack, propagating data such as totals, up the tree nodes. +Output completed nodes in the request formats. + +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. (On OSX the Graphviz +application will be started automatically.) + +The --db output is a SQLite database. The db schema is very subject to change. +This output is destined to be the primary one. The other output types will +probably become separate programs that read the db. + +=pod + # Needs to be generalized to support pluggable output formats. # Actually it needs to be split so sizeme_store.pl only does the store # and another program drives the output with plugins. diff --git a/lib/Devel/SizeMe.pm b/lib/Devel/SizeMe.pm index 5391e81..64b34b1 100644 --- a/lib/Devel/SizeMe.pm +++ b/lib/Devel/SizeMe.pm @@ -32,12 +32,15 @@ $VERSION = '0.02'; $warn = 1; $dangle = 0; ## Set true to enable warnings about dangling pointers -$ENV{SIZEME} ||= "| sizeme_store.pl --showid --db=sizeme.db"; +if (not defined $ENV{SIZEME}) { + $ENV{SIZEME} = "| sizeme_store.pl --db=sizeme.db"; + warn qq{SIZEME env var not set, defaulting to "$ENV{SIZEME}"\n}; +} XSLoader::load( __PACKAGE__); END { - Devel::SizeMe::perl_size() if $do_size_at_end; + Devel::SizeMe::perl_size() if $do_size_at_end; # heap_size() } 1; @@ -45,22 +48,32 @@ __END__ =pod -Devel::SizeMe - Perl extension for finding the memory usage of Perl variables +Devel::SizeMe - Extension for extracting detailed memory usage information =head1 SYNOPSIS - use Devel::SizeMe qw(size total_size); +Manual usage: + + use Devel::SizeMe qw(total_size perl_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 ); + my $perl_size = perl_size(); + +Quick automatic usage: + + perl -d:SizeMe ... + =head1 DESCRIPTION -Acts like Devel::Size 0.77 if the SIZEME env var is not set. +NOTE: This is all rather alpha and anything may change. + +The functions traverse memory structures and return the total memory size in +bytes. See L for more information. -Except that it also provides perl_size() and heap_size() functions. +If the C 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. @@ -68,6 +81,7 @@ 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 L. 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. @@ -101,6 +115,12 @@ Please report bugs to: http://rt.cpan.org/NoAuth/Bugs.html?Dist=Devel-SizeMe +=head2 Automatic Mode + +If loaded using the perl C<-d> option (i.e., C) +then perl memory usage data will be written to a C file in the +current directory when the script ends. + =head1 COPYRIGHT Copyright (C) 2005 Dan Sugalski,