[perl5.git] / ext / Devel-Peek / Peek.pm

# Devel::Peek - A data debugging tool for the XS programmer
# The documentation is after the __END__

package Devel::Peek;

$VERSION = '1.12';
$XS_VERSION = $VERSION;
$VERSION = eval $VERSION;

require Exporter;
require XSLoader;

@ISA = qw(Exporter);
@EXPORT = qw(Dump mstat DeadCode DumpArray DumpWithOP DumpProg
	     fill_mstats mstats_fillhash mstats2hash runops_debug debug_flags);
@EXPORT_OK = qw(SvREFCNT SvREFCNT_inc SvREFCNT_dec CvGV);
%EXPORT_TAGS = ('ALL' => [@EXPORT, @EXPORT_OK]);

XSLoader::load();

sub import {
  my $c = shift;
  my $ops_rx = qr/^:opd(=[stP]*)?\b/;
  my @db = grep m/$ops_rx/, @_;
  @_ = grep !m/$ops_rx/, @_;
  if (@db) {
    die "Too many :opd options" if @db > 1;
    runops_debug(1);
    my $flags = ($db[0] =~ m/$ops_rx/ and $1);
    $flags = 'st' unless defined $flags;
    my $f = 0;
    $f |= 2  if $flags =~ /s/;
    $f |= 8  if $flags =~ /t/;
    $f |= 64 if $flags =~ /P/;
    $^D |= $f if $f;
  }
  unshift @_, $c;
  goto &Exporter::import;
}

sub DumpWithOP ($;$) {
   local($Devel::Peek::dump_ops)=1;
   my $depth = @_ > 1 ? $_[1] : 4 ;
   Dump($_[0],$depth);
}

$D_flags = 'psltocPmfrxuLHXDSTR';

sub debug_flags (;$) {
  my $out = "";
  for my $i (0 .. length($D_flags)-1) {
    $out .= substr $D_flags, $i, 1 if $^D & (1<<$i);
  }
  my $arg = shift;
  my $num = $arg;
  if (defined $arg and $arg =~ /\D/) {
    die "unknown flags in debug_flags()" if $arg =~ /[^-$D_flags]/;
    my ($on,$off) = split /-/, "$arg-";
    $num = $^D;
    $num |=  (1<<index($D_flags, $_)) for split //, $on;
    $num &= ~(1<<index($D_flags, $_)) for split //, $off;
  }
  $^D = $num if defined $arg;
  $out
}

1;
__END__

=head1 NAME

Devel::Peek - A data debugging tool for the XS programmer

=head1 SYNOPSIS

        use Devel::Peek;
        Dump( $a );
        Dump( $a, 5 );
        DumpArray( 5, $a, $b, ... );
	mstat "Point 5";

        use Devel::Peek ':opd=st';

=head1 DESCRIPTION

Devel::Peek contains functions which allows raw Perl datatypes to be
manipulated from a Perl script.  This is used by those who do XS programming
to check that the data they are sending from C to Perl looks as they think
it should look.  The trick, then, is to know what the raw datatype is
supposed to look like when it gets to Perl.  This document offers some tips
and hints to describe good and bad raw data.

It is very possible that this document will fall far short of being useful
to the casual reader.  The reader is expected to understand the material in
the first few sections of L<perlguts>.

Devel::Peek supplies a C<Dump()> function which can dump a raw Perl
datatype, and C<mstat("marker")> function to report on memory usage
(if perl is compiled with corresponding option).  The function
DeadCode() provides statistics on the data "frozen" into inactive
C<CV>.  Devel::Peek also supplies C<SvREFCNT()>, C<SvREFCNT_inc()>, and
C<SvREFCNT_dec()> which can query, increment, and decrement reference
counts on SVs.  This document will take a passive, and safe, approach
to data debugging and for that it will describe only the C<Dump()>
function.

Function C<DumpArray()> allows dumping of multiple values (useful when you
need to analyze returns of functions).

The global variable $Devel::Peek::pv_limit can be set to limit the
number of character printed in various string values.  Setting it to 0
means no limit.

If C<use Devel::Peek> directive has a C<:opd=FLAGS> argument,
this switches on debugging of opcode dispatch.  C<FLAGS> should be a
combination of C<s>, C<t>, and C<P> (see B<-D> flags in L<perlrun>).
C<:opd> is a shortcut for C<:opd=st>.

=head2 Runtime debugging

C<CvGV($cv)> return one of the globs associated to a subroutine reference $cv.

debug_flags() returns a string representation of C<$^D> (similar to
what is allowed for B<-D> flag).  When called with a numeric argument,
sets $^D to the corresponding value.  When called with an argument of
the form C<"flags-flags">, set on/off bits of C<$^D> corresponding to
letters before/after C<->.  (The returned value is for C<$^D> before
the modification.)

runops_debug() returns true if the current I<opcode dispatcher> is the
debugging one.  When called with an argument, switches to debugging or
non-debugging dispatcher depending on the argument (active for
newly-entered subs/etc only).  (The returned value is for the dispatcher before the modification.)

=head2 Memory footprint debugging

When perl is compiled with support for memory footprint debugging
(default with Perl's malloc()), Devel::Peek provides an access to this API.

Use mstat() function to emit a memory state statistic to the terminal.
For more information on the format of output of mstat() see
L<perldebguts/Using $ENV{PERL_DEBUG_MSTATS}>.

Three additional functions allow access to this statistic from Perl.
First, use C<mstats_fillhash(%hash)> to get the information contained
in the output of mstat() into %hash. The field of this hash are

  minbucket nbuckets sbrk_good sbrk_slack sbrked_remains sbrks
  start_slack topbucket topbucket_ev topbucket_odd total total_chain
  total_sbrk totfree

Two additional fields C<free>, C<used> contain array references which
provide per-bucket count of free and used chunks.  Two other fields
C<mem_size>, C<available_size> contain array references which provide
the information about the allocated size and usable size of chunks in
each bucket.  Again, see L<perldebguts/Using $ENV{PERL_DEBUG_MSTATS}>
for details.


Keep in mind that only the first several "odd-numbered" buckets are
used, so the information on size of the "odd-numbered" buckets which are
not used is probably meaningless.

The information in

 mem_size available_size minbucket nbuckets

is the property of a particular build of perl, and does not depend on
the current process.  If you do not provide the optional argument to
the functions mstats_fillhash(), fill_mstats(), mstats2hash(), then
the information in fields C<mem_size>, C<available_size> is not
updated.

C<fill_mstats($buf)> is a much cheaper call (both speedwise and
memory-wise) which collects the statistic into $buf in
machine-readable form.  At a later moment you may need to call
C<mstats2hash($buf, %hash)> to use this information to fill %hash.

All three APIs C<fill_mstats($buf)>, C<mstats_fillhash(%hash)>, and
C<mstats2hash($buf, %hash)> are designed to allocate no memory if used
I<the second time> on the same $buf and/or %hash.

So, if you want to collect memory info in a cycle, you may call

  $#buf = 999;
  fill_mstats($_) for @buf;
  mstats_fillhash(%report, 1);		# Static info too

  foreach (@buf) {
    # Do something...
    fill_mstats $_;			# Collect statistic
  }
  foreach (@buf) {
    mstats2hash($_, %report);		# Preserve static info
    # Do something with %report
  }

=head1 EXAMPLES

The following examples don't attempt to show everything as that would be a
monumental task, and, frankly, we don't want this manpage to be an internals
document for Perl.  The examples do demonstrate some basics of the raw Perl
datatypes, and should suffice to get most determined people on their way.
There are no guidewires or safety nets, nor blazed trails, so be prepared to
travel alone from this point and on and, if at all possible, don't fall into
the quicksand (it's bad for business).

Oh, one final bit of advice: take L<perlguts> with you.  When you return we
expect to see it well-thumbed.

=head2 A simple scalar string

Let's begin by looking a simple scalar which is holding a string.

        use Devel::Peek;
        $a = 42; $a = "hello";
        Dump $a;

The output:

        SV = PVIV(0xbc288) at 0xbe9a8
          REFCNT = 1
          FLAGS = (POK,pPOK)
          IV = 42
          PV = 0xb2048 "hello"\0
          CUR = 5
          LEN = 8

This says C<$a> is an SV, a scalar.  The scalar type is a PVIV, which is
capable of holding an integer (IV) and/or a string (PV) value. The scalar's
head is allocated at address 0xbe9a8, while the body is at 0xbc288.
Its reference count is 1.  It has the C<POK> flag set, meaning its
current PV field is valid.  Because POK is set we look at the PV item
to see what is in the scalar.  The \0 at the end indicate that this
PV is properly NUL-terminated.
Note that the IV field still contains its old numeric value, but because
FLAGS doesn't have IOK set, we must ignore the IV item.
CUR indicates the number of characters in the PV.  LEN indicates the
number of bytes allocated for the PV (at least one more than CUR, because
LEN includes an extra byte for the end-of-string marker, then usually
rounded up to some efficient allocation unit).

=head2 A simple scalar number

If the scalar contains a number the raw SV will be leaner.

        use Devel::Peek;
        $a = 42;
        Dump $a;

The output:

        SV = IV(0xbc818) at 0xbe9a8
          REFCNT = 1
          FLAGS = (IOK,pIOK)
          IV = 42

This says C<$a> is an SV, a scalar.  The scalar is an IV, a number.  Its
reference count is 1.  It has the C<IOK> flag set, meaning it is currently
being evaluated as a number.  Because IOK is set we look at the IV item to
see what is in the scalar.

=head2 A simple scalar with an extra reference

If the scalar from the previous example had an extra reference:

        use Devel::Peek;
        $a = 42;
        $b = \$a;
        Dump $a;

The output:

        SV = IV(0xbe860) at 0xbe9a8
          REFCNT = 2
          FLAGS = (IOK,pIOK)
          IV = 42

Notice that this example differs from the previous example only in its
reference count.  Compare this to the next example, where we dump C<$b>
instead of C<$a>.

=head2 A reference to a simple scalar

This shows what a reference looks like when it references a simple scalar.

        use Devel::Peek;
        $a = 42;
        $b = \$a;
        Dump $b;

The output:

        SV = IV(0xf041c) at 0xbe9a0
          REFCNT = 1
          FLAGS = (ROK)
          RV = 0xbab08
          SV = IV(0xbe860) at 0xbe9a8
            REFCNT = 2
            FLAGS = (IOK,pIOK)
            IV = 42

Starting from the top, this says C<$b> is an SV.  The scalar is an IV,
which is capable of holding an integer or reference value.
It has the C<ROK> flag set, meaning it is a reference (rather than an
integer or string).  Notice that Dump
follows the reference and shows us what C<$b> was referencing.  We see the
same C<$a> that we found in the previous example.

Note that the value of C<RV> coincides with the numbers we see when we
stringify $b. The addresses inside IV() are addresses of
C<X***> structures which hold the current state of an C<SV>. This
address may change during lifetime of an SV.

=head2 A reference to an array

This shows what a reference to an array looks like.

        use Devel::Peek;
        $a = [42];
        Dump $a;

The output:

        SV = IV(0xc85998) at 0xc859a8
          REFCNT = 1
          FLAGS = (ROK)
          RV = 0xc70de8
          SV = PVAV(0xc71e10) at 0xc70de8
            REFCNT = 1
            FLAGS = ()
            ARRAY = 0xc7e820
            FILL = 0
            MAX = 0
            ARYLEN = 0x0
            FLAGS = (REAL)
            Elt No. 0
            SV = IV(0xc70f88) at 0xc70f98
              REFCNT = 1
              FLAGS = (IOK,pIOK)
              IV = 42

This says C<$a> is a reference (ROK), which points to
another SV which is a PVAV, an array.  The array has one element,
element zero, which is another SV. The field C<FILL> above indicates
the last element in the array, similar to C<$#$a>.

If C<$a> pointed to an array of two elements then we would see the
following.

        use Devel::Peek 'Dump';
        $a = [42,24];
        Dump $a;

The output:

        SV = IV(0x158c998) at 0x158c9a8
          REFCNT = 1
          FLAGS = (ROK)
          RV = 0x1577de8
          SV = PVAV(0x1578e10) at 0x1577de8
            REFCNT = 1
            FLAGS = ()
            ARRAY = 0x1585820
            FILL = 1
            MAX = 1
            ARYLEN = 0x0
            FLAGS = (REAL)
            Elt No. 0
            SV = IV(0x1577f88) at 0x1577f98
              REFCNT = 1
              FLAGS = (IOK,pIOK)
              IV = 42
            Elt No. 1
            SV = IV(0x158be88) at 0x158be98
              REFCNT = 1
              FLAGS = (IOK,pIOK)
              IV = 24

Note that C<Dump> will not report I<all> the elements in the array,
only several first (depending on how deep it already went into the
report tree).

=head2 A reference to a hash

The following shows the raw form of a reference to a hash.

        use Devel::Peek;
        $a = {hello=>42};
        Dump $a;

The output:

	SV = IV(0x8177858) at 0x816a618
	  REFCNT = 1
	  FLAGS = (ROK)
	  RV = 0x814fc10
	  SV = PVHV(0x8167768) at 0x814fc10
	    REFCNT = 1
	    FLAGS = (SHAREKEYS)
	    ARRAY = 0x816c5b8  (0:7, 1:1)
	    hash quality = 100.0%
	    KEYS = 1
	    FILL = 1
	    MAX = 7
	    RITER = -1
	    EITER = 0x0
	    Elt "hello" HASH = 0xc8fd181b
	    SV = IV(0x816c030) at 0x814fcf4
	      REFCNT = 1
	      FLAGS = (IOK,pIOK)
	      IV = 42

This shows C<$a> is a reference pointing to an SV.  That SV is a PVHV, a
hash. Fields RITER and EITER are used by C<L<perlfunc/each>>.

The "quality" of a hash is defined as the total number of comparisons needed
to access every element once, relative to the expected number needed for a
random hash. The value can go over 100%.

The total number of comparisons is equal to the sum of the squares of the
number of entries in each bucket.  For a random hash of C<<n>> keys into
C<<k>> buckets, the expected value is:

		n + n(n-1)/2k

=head2 Dumping a large array or hash

The C<Dump()> function, by default, dumps up to 4 elements from a
toplevel array or hash.  This number can be increased by supplying a
second argument to the function.

        use Devel::Peek;
        $a = [10,11,12,13,14];
        Dump $a;

Notice that C<Dump()> prints only elements 10 through 13 in the above code.
The following code will print all of the elements.

        use Devel::Peek 'Dump';
        $a = [10,11,12,13,14];
        Dump $a, 5;

=head2 A reference to an SV which holds a C pointer

This is what you really need to know as an XS programmer, of course.  When
an XSUB returns a pointer to a C structure that pointer is stored in an SV
and a reference to that SV is placed on the XSUB stack.  So the output from
an XSUB which uses something like the T_PTROBJ map might look something like
this:

        SV = IV(0xf381c) at 0xc859a8
          REFCNT = 1
          FLAGS = (ROK)
          RV = 0xb8ad8
          SV = PVMG(0xbb3c8) at 0xc859a0
            REFCNT = 1
            FLAGS = (OBJECT,IOK,pIOK)
            IV = 729160
            NV = 0
            PV = 0
            STASH = 0xc1d10       "CookBookB::Opaque"

This shows that we have an SV which is a reference, which points at another
SV.  In this case that second SV is a PVMG, a blessed scalar.  Because it is
blessed it has the C<OBJECT> flag set.  Note that an SV which holds a C
pointer also has the C<IOK> flag set.  The C<STASH> is set to the package
name which this SV was blessed into.

The output from an XSUB which uses something like the T_PTRREF map, which
doesn't bless the object, might look something like this:

        SV = IV(0xf381c) at 0xc859a8
          REFCNT = 1
          FLAGS = (ROK)
          RV = 0xb8ad8
          SV = PVMG(0xbb3c8) at 0xc859a0
            REFCNT = 1
            FLAGS = (IOK,pIOK)
            IV = 729160
            NV = 0
            PV = 0

=head2 A reference to a subroutine

Looks like this:

	SV = IV(0x24d2dd8) at 0x24d2de8
	  REFCNT = 1
	  FLAGS = (TEMP,ROK)
	  RV = 0x24e79d8
	  SV = PVCV(0x24e5798) at 0x24e79d8
	    REFCNT = 2
	    FLAGS = ()
	    COMP_STASH = 0x22c9c50	"main"
	    START = 0x22eed60 ===> 0
	    ROOT = 0x22ee490
	    GVGV::GV = 0x22de9d8	"MY" :: "top_targets"
	    FILE = "(eval 5)"
	    DEPTH = 0
	    FLAGS = 0x0
	    OUTSIDE_SEQ = 93
	    PADLIST = 0x22e9ed8
	    PADNAME = 0x22e9ec0(0x22eed00) PAD = 0x22e9ea8(0x22eecd0)
	    OUTSIDE = 0x22c9fb0 (MAIN)


This shows that 

=over 4

=item *

the subroutine is not an XSUB (since C<START> and C<ROOT> are
non-zero, and C<XSUB> is not listed, and is thus null);

=item *

that it was compiled in the package C<main>;

=item *

under the name C<MY::top_targets>; 

=item *

inside a 5th eval in the program;

=item *

it is not currently executed (see C<DEPTH>);

=item *

it has no prototype (C<PROTOTYPE> field is missing).

=back

=head1 EXPORTS

C<Dump>, C<mstat>, C<DeadCode>, C<DumpArray>, C<DumpWithOP> and
C<DumpProg>, C<fill_mstats>, C<mstats_fillhash>, C<mstats2hash> by
default. Additionally available C<SvREFCNT>, C<SvREFCNT_inc> and
C<SvREFCNT_dec>.

=head1 BUGS

Readers have been known to skip important parts of L<perlguts>, causing much
frustration for all.

=head1 AUTHOR

Ilya Zakharevich	ilya@math.ohio-state.edu

Copyright (c) 1995-98 Ilya Zakharevich. All rights reserved.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

Author of this software makes no claim whatsoever about suitability,
reliability, edability, editability or usability of this product, and
should not be kept liable for any damage resulting from the use of
it. If you can use it, you are in luck, if not, I should not be kept
responsible. Keep a handy copy of your backup tape at hand.

=head1 SEE ALSO

L<perlguts>, and L<perlguts>, again.

=cut
Commit	Line	Data
3967c732 JD	1	# Devel::Peek - A data debugging tool for the XS programmer
	2	# The documentation is after the __END__
	3
	4	package Devel::Peek;
	5
58af2c92	6	$VERSION = '1.12';
105cd853 YST	7	$XS_VERSION = $VERSION;
105cd853 YST	8	$VERSION = eval $VERSION;
3967c732 JD	9
3967c732 JD	10	require Exporter;
da4061d3	11	require XSLoader;
3967c732	12
9426adcd	13	@ISA = qw(Exporter);
d1424c31	14	@EXPORT = qw(Dump mstat DeadCode DumpArray DumpWithOP DumpProg
bd16a5f0	15	fill_mstats mstats_fillhash mstats2hash runops_debug debug_flags);
83ee9e09	16	@EXPORT_OK = qw(SvREFCNT SvREFCNT_inc SvREFCNT_dec CvGV);
3967c732 JD	17	%EXPORT_TAGS = ('ALL' => [@EXPORT, @EXPORT_OK]);
3967c732 JD	18
da4061d3	19	XSLoader::load();
3967c732	20
1045810a IZ	21	sub import {
	22	my $c = shift;
	23	my $ops_rx = qr/^:opd(=[stP]*)?\b/;
	24	my @db = grep m/$ops_rx/, @_;
	25	@_ = grep !m/$ops_rx/, @_;
	26	if (@db) {
	27	die "Too many :opd options" if @db > 1;
	28	runops_debug(1);
	29	my $flags = ($db[0] =~ m/$ops_rx/ and $1);
	30	$flags = 'st' unless defined $flags;
	31	my $f = 0;
	32	$f \|= 2 if $flags =~ /s/;
	33	$f \|= 8 if $flags =~ /t/;
	34	$f \|= 64 if $flags =~ /P/;
	35	$^D \|= $f if $f;
	36	}
	37	unshift @_, $c;
	38	goto &Exporter::import;
	39	}
	40
3967c732 JD	41	sub DumpWithOP ($;$) {
	42	local($Devel::Peek::dump_ops)=1;
	43	my $depth = @_ > 1 ? $_[1] : 4 ;
	44	Dump($_[0],$depth);
	45	}
	46
bd16a5f0 IZ	47	$D_flags = 'psltocPmfrxuLHXDSTR';
	48
	49	sub debug_flags (;$) {
	50	my $out = "";
	51	for my $i (0 .. length($D_flags)-1) {
	52	$out .= substr $D_flags, $i, 1 if $^D & (1<<$i);
	53	}
	54	my $arg = shift;
	55	my $num = $arg;
	56	if (defined $arg and $arg =~ /\D/) {
	57	die "unknown flags in debug_flags()" if $arg =~ /[^-$D_flags]/;
	58	my ($on,$off) = split /-/, "$arg-";
	59	$num = $^D;
	60	$num \|= (1<<index($D_flags, $_)) for split //, $on;
	61	$num &= ~(1<<index($D_flags, $_)) for split //, $off;
	62	}
	63	$^D = $num if defined $arg;
	64	$out
	65	}
	66
3967c732 JD	67	1;
	68	__END__
	69
	70	=head1 NAME
	71
	72	Devel::Peek - A data debugging tool for the XS programmer
	73
	74	=head1 SYNOPSIS
	75
	76	use Devel::Peek;
	77	Dump( $a );
	78	Dump( $a, 5 );
	79	DumpArray( 5, $a, $b, ... );
	80	mstat "Point 5";
	81
1045810a IZ	82	use Devel::Peek ':opd=st';
1045810a IZ	83
3967c732 JD	84	=head1 DESCRIPTION
	85
	86	Devel::Peek contains functions which allows raw Perl datatypes to be
	87	manipulated from a Perl script. This is used by those who do XS programming
	88	to check that the data they are sending from C to Perl looks as they think
	89	it should look. The trick, then, is to know what the raw datatype is
	90	supposed to look like when it gets to Perl. This document offers some tips
	91	and hints to describe good and bad raw data.
	92
	93	It is very possible that this document will fall far short of being useful
	94	to the casual reader. The reader is expected to understand the material in
	95	the first few sections of L<perlguts>.
	96
	97	Devel::Peek supplies a C<Dump()> function which can dump a raw Perl
	98	datatype, and C<mstat("marker")> function to report on memory usage
	99	(if perl is compiled with corresponding option). The function
	100	DeadCode() provides statistics on the data "frozen" into inactive
	101	C<CV>. Devel::Peek also supplies C<SvREFCNT()>, C<SvREFCNT_inc()>, and
	102	C<SvREFCNT_dec()> which can query, increment, and decrement reference
	103	counts on SVs. This document will take a passive, and safe, approach
	104	to data debugging and for that it will describe only the C<Dump()>
d1424c31	105	function.
3967c732 JD	106
3967c732 JD	107	Function C<DumpArray()> allows dumping of multiple values (useful when you
076c2fc0	108	need to analyze returns of functions).
3967c732 JD	109
	110	The global variable $Devel::Peek::pv_limit can be set to limit the
	111	number of character printed in various string values. Setting it to 0
	112	means no limit.
	113
1045810a IZ	114	If C<use Devel::Peek> directive has a C<:opd=FLAGS> argument,
	115	this switches on debugging of opcode dispatch. C<FLAGS> should be a
	116	combination of C<s>, C<t>, and C<P> (see B<-D> flags in L<perlrun>).
	117	C<:opd> is a shortcut for C<:opd=st>.
	118
bd16a5f0 IZ	119	=head2 Runtime debugging
	120
	121	C<CvGV($cv)> return one of the globs associated to a subroutine reference $cv.
	122
	123	debug_flags() returns a string representation of C<$^D> (similar to
	124	what is allowed for B<-D> flag). When called with a numeric argument,
	125	sets $^D to the corresponding value. When called with an argument of
	126	the form C<"flags-flags">, set on/off bits of C<$^D> corresponding to
	127	letters before/after C<->. (The returned value is for C<$^D> before
	128	the modification.)
	129
	130	runops_debug() returns true if the current I<opcode dispatcher> is the
	131	debugging one. When called with an argument, switches to debugging or
	132	non-debugging dispatcher depending on the argument (active for
	133	newly-entered subs/etc only). (The returned value is for the dispatcher before the modification.)
	134
d1424c31 IZ	135	=head2 Memory footprint debugging
	136
	137	When perl is compiled with support for memory footprint debugging
	138	(default with Perl's malloc()), Devel::Peek provides an access to this API.
	139
	140	Use mstat() function to emit a memory state statistic to the terminal.
	141	For more information on the format of output of mstat() see
9704a6c6	142	L<perldebguts/Using $ENV{PERL_DEBUG_MSTATS}>.
d1424c31 IZ	143
	144	Three additional functions allow access to this statistic from Perl.
	145	First, use C<mstats_fillhash(%hash)> to get the information contained
	146	in the output of mstat() into %hash. The field of this hash are
	147
555bd962 BG	148	minbucket nbuckets sbrk_good sbrk_slack sbrked_remains sbrks
	149	start_slack topbucket topbucket_ev topbucket_odd total total_chain
	150	total_sbrk totfree
d1424c31 IZ	151
	152	Two additional fields C<free>, C<used> contain array references which
	153	provide per-bucket count of free and used chunks. Two other fields
	154	C<mem_size>, C<available_size> contain array references which provide
	155	the information about the allocated size and usable size of chunks in
9704a6c6	156	each bucket. Again, see L<perldebguts/Using $ENV{PERL_DEBUG_MSTATS}>
d1424c31 IZ	157	for details.
d1424c31 IZ	158
b1e4fe07	159
d1424c31 IZ	160	Keep in mind that only the first several "odd-numbered" buckets are
	161	used, so the information on size of the "odd-numbered" buckets which are
	162	not used is probably meaningless.
	163
	164	The information in
	165
	166	mem_size available_size minbucket nbuckets
	167
	168	is the property of a particular build of perl, and does not depend on
	169	the current process. If you do not provide the optional argument to
	170	the functions mstats_fillhash(), fill_mstats(), mstats2hash(), then
	171	the information in fields C<mem_size>, C<available_size> is not
	172	updated.
	173
	174	C<fill_mstats($buf)> is a much cheaper call (both speedwise and
	175	memory-wise) which collects the statistic into $buf in
	176	machine-readable form. At a later moment you may need to call
	177	C<mstats2hash($buf, %hash)> to use this information to fill %hash.
	178
	179	All three APIs C<fill_mstats($buf)>, C<mstats_fillhash(%hash)>, and
	180	C<mstats2hash($buf, %hash)> are designed to allocate no memory if used
	181	I<the second time> on the same $buf and/or %hash.
	182
	183	So, if you want to collect memory info in a cycle, you may call
	184
	185	$#buf = 999;
	186	fill_mstats($_) for @buf;
	187	mstats_fillhash(%report, 1); # Static info too
	188
	189	foreach (@buf) {
	190	# Do something...
	191	fill_mstats $_; # Collect statistic
	192	}
	193	foreach (@buf) {
	194	mstats2hash($_, %report); # Preserve static info
	195	# Do something with %report
	196	}
	197
3967c732 JD	198	=head1 EXAMPLES
	199
	200	The following examples don't attempt to show everything as that would be a
	201	monumental task, and, frankly, we don't want this manpage to be an internals
	202	document for Perl. The examples do demonstrate some basics of the raw Perl
	203	datatypes, and should suffice to get most determined people on their way.
	204	There are no guidewires or safety nets, nor blazed trails, so be prepared to
	205	travel alone from this point and on and, if at all possible, don't fall into
	206	the quicksand (it's bad for business).
	207
	208	Oh, one final bit of advice: take L<perlguts> with you. When you return we
	209	expect to see it well-thumbed.
	210
	211	=head2 A simple scalar string
	212
	213	Let's begin by looking a simple scalar which is holding a string.
	214
a423dfdd	215	use Devel::Peek;
f64eb7e3	216	$a = 42; $a = "hello";
3967c732 JD	217	Dump $a;
	218
	219	The output:
	220
f64eb7e3	221	SV = PVIV(0xbc288) at 0xbe9a8
3967c732 JD	222	REFCNT = 1
3967c732 JD	223	FLAGS = (POK,pPOK)
f64eb7e3	224	IV = 42
3967c732 JD	225	PV = 0xb2048 "hello"\0
3967c732 JD	226	CUR = 5
f64eb7e3	227	LEN = 8
3967c732	228
f64eb7e3 DM	229	This says C<$a> is an SV, a scalar. The scalar type is a PVIV, which is
	230	capable of holding an integer (IV) and/or a string (PV) value. The scalar's
	231	head is allocated at address 0xbe9a8, while the body is at 0xbc288.
3967c732 JD	232	Its reference count is 1. It has the C<POK> flag set, meaning its
	233	current PV field is valid. Because POK is set we look at the PV item
	234	to see what is in the scalar. The \0 at the end indicate that this
	235	PV is properly NUL-terminated.
f64eb7e3 DM	236	Note that the IV field still contains its old numeric value, but because
	237	FLAGS doesn't have IOK set, we must ignore the IV item.
	238	CUR indicates the number of characters in the PV. LEN indicates the
	239	number of bytes allocated for the PV (at least one more than CUR, because
	240	LEN includes an extra byte for the end-of-string marker, then usually
	241	rounded up to some efficient allocation unit).
3967c732 JD	242
	243	=head2 A simple scalar number
	244
	245	If the scalar contains a number the raw SV will be leaner.
	246
a423dfdd	247	use Devel::Peek;
3967c732 JD	248	$a = 42;
	249	Dump $a;
	250
	251	The output:
	252
f64eb7e3	253	SV = IV(0xbc818) at 0xbe9a8
3967c732 JD	254	REFCNT = 1
	255	FLAGS = (IOK,pIOK)
	256	IV = 42
	257
	258	This says C<$a> is an SV, a scalar. The scalar is an IV, a number. Its
	259	reference count is 1. It has the C<IOK> flag set, meaning it is currently
	260	being evaluated as a number. Because IOK is set we look at the IV item to
	261	see what is in the scalar.
	262
	263	=head2 A simple scalar with an extra reference
	264
	265	If the scalar from the previous example had an extra reference:
	266
a423dfdd	267	use Devel::Peek;
3967c732 JD	268	$a = 42;
	269	$b = \$a;
	270	Dump $a;
	271
	272	The output:
	273
f64eb7e3	274	SV = IV(0xbe860) at 0xbe9a8
3967c732 JD	275	REFCNT = 2
	276	FLAGS = (IOK,pIOK)
	277	IV = 42
	278
	279	Notice that this example differs from the previous example only in its
	280	reference count. Compare this to the next example, where we dump C<$b>
	281	instead of C<$a>.
	282
	283	=head2 A reference to a simple scalar
	284
	285	This shows what a reference looks like when it references a simple scalar.
	286
a423dfdd	287	use Devel::Peek;
3967c732 JD	288	$a = 42;
	289	$b = \$a;
	290	Dump $b;
	291
	292	The output:
	293
f64eb7e3	294	SV = IV(0xf041c) at 0xbe9a0
3967c732 JD	295	REFCNT = 1
	296	FLAGS = (ROK)
	297	RV = 0xbab08
f64eb7e3 DM	298	SV = IV(0xbe860) at 0xbe9a8
	299	REFCNT = 2
	300	FLAGS = (IOK,pIOK)
	301	IV = 42
	302
	303	Starting from the top, this says C<$b> is an SV. The scalar is an IV,
	304	which is capable of holding an integer or reference value.
	305	It has the C<ROK> flag set, meaning it is a reference (rather than an
	306	integer or string). Notice that Dump
3967c732 JD	307	follows the reference and shows us what C<$b> was referencing. We see the
	308	same C<$a> that we found in the previous example.
	309
	310	Note that the value of C<RV> coincides with the numbers we see when we
f64eb7e3 DM	311	stringify $b. The addresses inside IV() are addresses of
f64eb7e3 DM	312	C<X***> structures which hold the current state of an C<SV>. This
3967c732 JD	313	address may change during lifetime of an SV.
	314
	315	=head2 A reference to an array
	316
	317	This shows what a reference to an array looks like.
	318
a423dfdd	319	use Devel::Peek;
3967c732 JD	320	$a = [42];
	321	Dump $a;
	322
	323	The output:
	324
f64eb7e3	325	SV = IV(0xc85998) at 0xc859a8
3967c732 JD	326	REFCNT = 1
3967c732 JD	327	FLAGS = (ROK)
f64eb7e3 DM	328	RV = 0xc70de8
	329	SV = PVAV(0xc71e10) at 0xc70de8
	330	REFCNT = 1
	331	FLAGS = ()
	332	ARRAY = 0xc7e820
	333	FILL = 0
	334	MAX = 0
	335	ARYLEN = 0x0
	336	FLAGS = (REAL)
	337	Elt No. 0
	338	SV = IV(0xc70f88) at 0xc70f98
	339	REFCNT = 1
	340	FLAGS = (IOK,pIOK)
	341	IV = 42
	342
	343	This says C<$a> is a reference (ROK), which points to
3967c732 JD	344	another SV which is a PVAV, an array. The array has one element,
	345	element zero, which is another SV. The field C<FILL> above indicates
	346	the last element in the array, similar to C<$#$a>.
	347
	348	If C<$a> pointed to an array of two elements then we would see the
	349	following.
	350
	351	use Devel::Peek 'Dump';
	352	$a = [42,24];
	353	Dump $a;
	354
	355	The output:
	356
f64eb7e3	357	SV = IV(0x158c998) at 0x158c9a8
3967c732 JD	358	REFCNT = 1
3967c732 JD	359	FLAGS = (ROK)
f64eb7e3 DM	360	RV = 0x1577de8
	361	SV = PVAV(0x1578e10) at 0x1577de8
	362	REFCNT = 1
	363	FLAGS = ()
	364	ARRAY = 0x1585820
	365	FILL = 1
	366	MAX = 1
	367	ARYLEN = 0x0
	368	FLAGS = (REAL)
	369	Elt No. 0
	370	SV = IV(0x1577f88) at 0x1577f98
	371	REFCNT = 1
	372	FLAGS = (IOK,pIOK)
	373	IV = 42
	374	Elt No. 1
	375	SV = IV(0x158be88) at 0x158be98
	376	REFCNT = 1
	377	FLAGS = (IOK,pIOK)
	378	IV = 24
3967c732 JD	379
	380	Note that C<Dump> will not report I<all> the elements in the array,
	381	only several first (depending on how deep it already went into the
	382	report tree).
	383
	384	=head2 A reference to a hash
	385
	386	The following shows the raw form of a reference to a hash.
	387
a423dfdd	388	use Devel::Peek;
3967c732 JD	389	$a = {hello=>42};
	390	Dump $a;
	391
	392	The output:
	393
f64eb7e3	394	SV = IV(0x8177858) at 0x816a618
d5889220 T	395	REFCNT = 1
	396	FLAGS = (ROK)
	397	RV = 0x814fc10
	398	SV = PVHV(0x8167768) at 0x814fc10
	399	REFCNT = 1
	400	FLAGS = (SHAREKEYS)
d5889220 T	401	ARRAY = 0x816c5b8 (0:7, 1:1)
	402	hash quality = 100.0%
	403	KEYS = 1
	404	FILL = 1
	405	MAX = 7
	406	RITER = -1
	407	EITER = 0x0
	408	Elt "hello" HASH = 0xc8fd181b
	409	SV = IV(0x816c030) at 0x814fcf4
	410	REFCNT = 1
	411	FLAGS = (IOK,pIOK)
	412	IV = 42
3967c732 JD	413
3967c732 JD	414	This shows C<$a> is a reference pointing to an SV. That SV is a PVHV, a
b1e4fe07	415	hash. Fields RITER and EITER are used by C<L<perlfunc/each>>.
3967c732	416
d5889220 T	417	The "quality" of a hash is defined as the total number of comparisons needed
	418	to access every element once, relative to the expected number needed for a
	419	random hash. The value can go over 100%.
	420
	421	The total number of comparisons is equal to the sum of the squares of the
	422	number of entries in each bucket. For a random hash of C<<n>> keys into
	423	C<<k>> buckets, the expected value is:
	424
	425	n + n(n-1)/2k
	426
3967c732 JD	427	=head2 Dumping a large array or hash
	428
	429	The C<Dump()> function, by default, dumps up to 4 elements from a
	430	toplevel array or hash. This number can be increased by supplying a
	431	second argument to the function.
	432
a423dfdd	433	use Devel::Peek;
3967c732 JD	434	$a = [10,11,12,13,14];
	435	Dump $a;
	436
	437	Notice that C<Dump()> prints only elements 10 through 13 in the above code.
	438	The following code will print all of the elements.
	439
	440	use Devel::Peek 'Dump';
	441	$a = [10,11,12,13,14];
	442	Dump $a, 5;
	443
	444	=head2 A reference to an SV which holds a C pointer
	445
	446	This is what you really need to know as an XS programmer, of course. When
	447	an XSUB returns a pointer to a C structure that pointer is stored in an SV
	448	and a reference to that SV is placed on the XSUB stack. So the output from
	449	an XSUB which uses something like the T_PTROBJ map might look something like
	450	this:
	451
f64eb7e3	452	SV = IV(0xf381c) at 0xc859a8
3967c732 JD	453	REFCNT = 1
	454	FLAGS = (ROK)
	455	RV = 0xb8ad8
f64eb7e3 DM	456	SV = PVMG(0xbb3c8) at 0xc859a0
	457	REFCNT = 1
	458	FLAGS = (OBJECT,IOK,pIOK)
	459	IV = 729160
	460	NV = 0
	461	PV = 0
	462	STASH = 0xc1d10 "CookBookB::Opaque"
	463
	464	This shows that we have an SV which is a reference, which points at another
3967c732 JD	465	SV. In this case that second SV is a PVMG, a blessed scalar. Because it is
	466	blessed it has the C<OBJECT> flag set. Note that an SV which holds a C
	467	pointer also has the C<IOK> flag set. The C<STASH> is set to the package
	468	name which this SV was blessed into.
	469
	470	The output from an XSUB which uses something like the T_PTRREF map, which
	471	doesn't bless the object, might look something like this:
	472
f64eb7e3	473	SV = IV(0xf381c) at 0xc859a8
3967c732 JD	474	REFCNT = 1
	475	FLAGS = (ROK)
	476	RV = 0xb8ad8
f64eb7e3 DM	477	SV = PVMG(0xbb3c8) at 0xc859a0
	478	REFCNT = 1
	479	FLAGS = (IOK,pIOK)
	480	IV = 729160
	481	NV = 0
	482	PV = 0
3967c732 JD	483
	484	=head2 A reference to a subroutine
	485
	486	Looks like this:
	487
f64eb7e3	488	SV = IV(0x24d2dd8) at 0x24d2de8
3967c732 JD	489	REFCNT = 1
3967c732 JD	490	FLAGS = (TEMP,ROK)
f64eb7e3 DM	491	RV = 0x24e79d8
	492	SV = PVCV(0x24e5798) at 0x24e79d8
	493	REFCNT = 2
	494	FLAGS = ()
	495	COMP_STASH = 0x22c9c50 "main"
	496	START = 0x22eed60 ===> 0
	497	ROOT = 0x22ee490
	498	GVGV::GV = 0x22de9d8 "MY" :: "top_targets"
	499	FILE = "(eval 5)"
	500	DEPTH = 0
	501	FLAGS = 0x0
	502	OUTSIDE_SEQ = 93
	503	PADLIST = 0x22e9ed8
	504	PADNAME = 0x22e9ec0(0x22eed00) PAD = 0x22e9ea8(0x22eecd0)
	505	OUTSIDE = 0x22c9fb0 (MAIN)
	506
3967c732 JD	507
	508	This shows that
	509
bbc7dcd2	510	=over 4
3967c732	511
a45bd81d	512	=item *
3967c732 JD	513
3967c732 JD	514	the subroutine is not an XSUB (since C<START> and C<ROOT> are
f64eb7e3	515	non-zero, and C<XSUB> is not listed, and is thus null);
3967c732	516
a45bd81d	517	=item *
3967c732 JD	518
	519	that it was compiled in the package C<main>;
	520
a45bd81d	521	=item *
3967c732 JD	522
	523	under the name C<MY::top_targets>;
	524
a45bd81d	525	=item *
3967c732 JD	526
	527	inside a 5th eval in the program;
	528
a45bd81d	529	=item *
3967c732 JD	530
	531	it is not currently executed (see C<DEPTH>);
	532
a45bd81d	533	=item *
3967c732 JD	534
	535	it has no prototype (C<PROTOTYPE> field is missing).
	536
a45bd81d	537	=back
3967c732 JD	538
	539	=head1 EXPORTS
	540
	541	C<Dump>, C<mstat>, C<DeadCode>, C<DumpArray>, C<DumpWithOP> and
7c6ca602	542	C<DumpProg>, C<fill_mstats>, C<mstats_fillhash>, C<mstats2hash> by
d1424c31 IZ	543	default. Additionally available C<SvREFCNT>, C<SvREFCNT_inc> and
d1424c31 IZ	544	C<SvREFCNT_dec>.
3967c732 JD	545
	546	=head1 BUGS
	547
	548	Readers have been known to skip important parts of L<perlguts>, causing much
	549	frustration for all.
	550
	551	=head1 AUTHOR
	552
	553	Ilya Zakharevich ilya@math.ohio-state.edu
	554
	555	Copyright (c) 1995-98 Ilya Zakharevich. All rights reserved.
	556	This program is free software; you can redistribute it and/or
	557	modify it under the same terms as Perl itself.
	558
	559	Author of this software makes no claim whatsoever about suitability,
	560	reliability, edability, editability or usability of this product, and
	561	should not be kept liable for any damage resulting from the use of
	562	it. If you can use it, you are in luck, if not, I should not be kept
	563	responsible. Keep a handy copy of your backup tape at hand.
	564
	565	=head1 SEE ALSO
	566
	567	L<perlguts>, and L<perlguts>, again.
	568
	569	=cut