=head1 NAME

Internals::DumpArenas - Dump perl memory

=head1 DESCRIPTION

Dumps all of perl's regular values. This iterates over all values
reachable by the perl's normal memory management.

=head1 FUNCTIONS

=head2 DumpArenas()

Dumps everything to STDERR.

=head1 OUTPUT FORMAT

=head2 INDIVIDUAL VALUES

At a basic level, each and every perl value is printed using the same
facility as the core function L<Devel::Peek::Dump>. This is a
low-level, verbose way of describing perl values:

  use Devel::Peek;
  Dump("Hello world!\n");
  Dump(42);

produces the following output. You can see the values "Hello world!\n"
and 42 but also other details of perl's implementation.

  SV = PV(0x9919128) at 0x992a7d8
    REFCNT = 1
    FLAGS = (POK,READONLY,pPOK)
    PV = 0x992f638 "Hello world!\n"\0
    CUR = 13
    LEN = 16
  SV = IV(0x992a7f4) at 0x992a7f8
    REFCNT = 1
    FLAGS = (IOK,READONLY,pIOK)
    IV = 42

=head2 Arrays

Array containers also consume space and hold pointers to perl
values. The general format is:

  AvARRAY(0x1123e150) = {address,address ...}

Arrays which have more entries allocated than used will show a
doubled-up entry with the "extra" part being visible at the end. The
general format is:

  AvARRAY(0x1117f3c0) = {{addresses}{addresses}}

and a specific example:

  AvARRAY(0x1117f3c0) = {{0x104a7b98,PL_sv_undef,PL_sv_undef}{PL_sv_undef}}

=head2 Hashes

Hash containers also consume space and hold pointers to perl
values. The general format is:

  HvARRAY(address)
    [address "key value"] => address
    [address "key value"] => address
    ...

A specific example:

  ARRAY(0x1123e1e0)
    [0x814a7c0 "_percentage"] => 0x104d5b78
    [0x814a840 "_description"] => 0x104d5b90
    [0x814a780 "_treatment_id"] => 0x104d5b60

=head2 Pointers

Pointers to special addresses are displayed symbolically:

=over

=item PL_sv_undef

=item PL_sv_yes

=item PL_sv_no

=item PL_sv_placeholder

=back

=head2

=head2 ARENA MAP

Each arena map is also printed as work is begun and finished.

  START ARENA = (0xfe4f360-0x1004f340)
  ...
  END ARENA = (0xfe4f360-0x1004f340)

Empty slots in the arena maps are printed as:

  AVAILABLE(0x10abf758)

=head1 BUGS

Please report any bugs or feature requests to
C<bug-Internals-DumpArenas at rt.cpan.org>, or through the web
interface at
L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Internals-DumpArenas>.
I will be notified, and then you'll automatically be notified of
progress on your bug as I make changes.

=head1 SUPPORT

You can find documentation for this module with the perldoc command.

  perldoc Internals::DumpArenas

You can also look for information at:

=over

=item * RT: CPAN's request tracker

L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Internals-DumpArenas>

=item * AnnoCPAN: Annotated CPAN documentation

L<http://annocpan.org/dist/Internals-DumpArenas>

=item * CPAN Ratings

L<http://cpanratings.perl.org/d/Internals-DumpArenas>

=item * Search CPAN

L<http://search.cpan.org/dist/Internals-DumpArenas/>

=back

=head1 ACKNOWLEDGEMENTS

Brian Rice, totally.

I was inspired by L<http://netjam.org/spoon/viz/> and want to make the
same thing for perl.

=head1 COPYRIGHT & LICENSE

Copyright 2009-2011 Josh Jore, all rights reserved.

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

=head1 SOURCE AVAILABILITY

This source is in Github: L<git://github.com/jbenjore/internals-dumparenas.git>

=head1 AUTHOR

Josh Jore
