ext/Devel-Peek/Peek.pm

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