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.03';
   7 $XS_VERSION = $VERSION;
   8 $VERSION = eval $VERSION;
   9
  10 require Exporter;
  11 use 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 SvREFCNT_inc SvREFCNT_dec CvGV);
  17 %EXPORT_TAGS = ('ALL' => [@EXPORT, @EXPORT_OK]);
  18
  19 XSLoader::load 'Devel::Peek';
  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 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
  82         use Devel::Peek ':opd=st';
  83
  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()>
 105 function.
 106
 107 Function C<DumpArray()> allows dumping of multiple values (useful when you
 108 need to analyze returns of functions).
 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
 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
 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
 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
 142 L<perldebguts/Using C<$ENV{PERL_DEBUG_MSTATS}>>.
 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
 148   minbucket nbuckets sbrk_good sbrk_slack sbrked_remains sbrks start_slack
 149   topbucket topbucket_ev topbucket_odd total total_chain total_sbrk totfree
 150
 151 Two additional fields C<free>, C<used> contain array references which
 152 provide per-bucket count of free and used chunks.  Two other fields
 153 C<mem_size>, C<available_size> contain array references which provide
 154 the information about the allocated size and usable size of chunks in
 155 each bucket.  Again, see L<perldebguts/Using C<$ENV{PERL_DEBUG_MSTATS}>>
 156 for details.
 157
 158 Keep in mind that only the first several "odd-numbered" buckets are
 159 used, so the information on size of the "odd-numbered" buckets which are
 160 not used is probably meaningless.
 161
 162 The information in
 163
 164  mem_size available_size minbucket nbuckets
 165
 166 is the property of a particular build of perl, and does not depend on
 167 the current process.  If you do not provide the optional argument to
 168 the functions mstats_fillhash(), fill_mstats(), mstats2hash(), then
 169 the information in fields C<mem_size>, C<available_size> is not
 170 updated.
 171
 172 C<fill_mstats($buf)> is a much cheaper call (both speedwise and
 173 memory-wise) which collects the statistic into $buf in
 174 machine-readable form.  At a later moment you may need to call
 175 C<mstats2hash($buf, %hash)> to use this information to fill %hash.
 176
 177 All three APIs C<fill_mstats($buf)>, C<mstats_fillhash(%hash)>, and
 178 C<mstats2hash($buf, %hash)> are designed to allocate no memory if used
 179 I<the second time> on the same $buf and/or %hash.
 180
 181 So, if you want to collect memory info in a cycle, you may call
 182
 183   $#buf = 999;
 184   fill_mstats($_) for @buf;
 185   mstats_fillhash(%report, 1);          # Static info too
 186
 187   foreach (@buf) {
 188     # Do something...
 189     fill_mstats $_;                     # Collect statistic
 190   }
 191   foreach (@buf) {
 192     mstats2hash($_, %report);           # Preserve static info
 193     # Do something with %report
 194   }
 195
 196 =head1 EXAMPLES
 197
 198 The following examples don't attempt to show everything as that would be a
 199 monumental task, and, frankly, we don't want this manpage to be an internals
 200 document for Perl.  The examples do demonstrate some basics of the raw Perl
 201 datatypes, and should suffice to get most determined people on their way.
 202 There are no guidewires or safety nets, nor blazed trails, so be prepared to
 203 travel alone from this point and on and, if at all possible, don't fall into
 204 the quicksand (it's bad for business).
 205
 206 Oh, one final bit of advice: take L<perlguts> with you.  When you return we
 207 expect to see it well-thumbed.
 208
 209 =head2 A simple scalar string
 210
 211 Let's begin by looking a simple scalar which is holding a string.
 212
 213         use Devel::Peek;
 214         $a = "hello";
 215         Dump $a;
 216
 217 The output:
 218
 219         SV = PVIV(0xbc288)
 220           REFCNT = 1
 221           FLAGS = (POK,pPOK)
 222           IV = 0
 223           PV = 0xb2048 "hello"\0
 224           CUR = 5
 225           LEN = 6
 226
 227 This says C<$a> is an SV, a scalar.  The scalar is a PVIV, a string.
 228 Its reference count is 1.  It has the C<POK> flag set, meaning its
 229 current PV field is valid.  Because POK is set we look at the PV item
 230 to see what is in the scalar.  The \0 at the end indicate that this
 231 PV is properly NUL-terminated.
 232 If the FLAGS had been IOK we would look
 233 at the IV item.  CUR indicates the number of characters in the PV.
 234 LEN indicates the number of bytes requested for the PV (one more than
 235 CUR, in this case, because LEN includes an extra byte for the
 236 end-of-string marker).
 237
 238 =head2 A simple scalar number
 239
 240 If the scalar contains a number the raw SV will be leaner.
 241
 242         use Devel::Peek;
 243         $a = 42;
 244         Dump $a;
 245
 246 The output:
 247
 248         SV = IV(0xbc818)
 249           REFCNT = 1
 250           FLAGS = (IOK,pIOK)
 251           IV = 42
 252
 253 This says C<$a> is an SV, a scalar.  The scalar is an IV, a number.  Its
 254 reference count is 1.  It has the C<IOK> flag set, meaning it is currently
 255 being evaluated as a number.  Because IOK is set we look at the IV item to
 256 see what is in the scalar.
 257
 258 =head2 A simple scalar with an extra reference
 259
 260 If the scalar from the previous example had an extra reference:
 261
 262         use Devel::Peek;
 263         $a = 42;
 264         $b = \$a;
 265         Dump $a;
 266
 267 The output:
 268
 269         SV = IV(0xbe860)
 270           REFCNT = 2
 271           FLAGS = (IOK,pIOK)
 272           IV = 42
 273
 274 Notice that this example differs from the previous example only in its
 275 reference count.  Compare this to the next example, where we dump C<$b>
 276 instead of C<$a>.
 277
 278 =head2 A reference to a simple scalar
 279
 280 This shows what a reference looks like when it references a simple scalar.
 281
 282         use Devel::Peek;
 283         $a = 42;
 284         $b = \$a;
 285         Dump $b;
 286
 287 The output:
 288
 289         SV = RV(0xf041c)
 290           REFCNT = 1
 291           FLAGS = (ROK)
 292           RV = 0xbab08
 293         SV = IV(0xbe860)
 294           REFCNT = 2
 295           FLAGS = (IOK,pIOK)
 296           IV = 42
 297
 298 Starting from the top, this says C<$b> is an SV.  The scalar is an RV, a
 299 reference.  It has the C<ROK> flag set, meaning it is a reference.  Because
 300 ROK is set we have an RV item rather than an IV or PV.  Notice that Dump
 301 follows the reference and shows us what C<$b> was referencing.  We see the
 302 same C<$a> that we found in the previous example.
 303
 304 Note that the value of C<RV> coincides with the numbers we see when we
 305 stringify $b. The addresses inside RV() and IV() are addresses of
 306 C<X***> structure which holds the current state of an C<SV>. This
 307 address may change during lifetime of an SV.
 308
 309 =head2 A reference to an array
 310
 311 This shows what a reference to an array looks like.
 312
 313         use Devel::Peek;
 314         $a = [42];
 315         Dump $a;
 316
 317 The output:
 318
 319         SV = RV(0xf041c)
 320           REFCNT = 1
 321           FLAGS = (ROK)
 322           RV = 0xb2850
 323         SV = PVAV(0xbd448)
 324           REFCNT = 1
 325           FLAGS = ()
 326           IV = 0
 327           NV = 0
 328           ARRAY = 0xb2048
 329           ALLOC = 0xb2048
 330           FILL = 0
 331           MAX = 0
 332           ARYLEN = 0x0
 333           FLAGS = (REAL)
 334         Elt No. 0 0xb5658
 335         SV = IV(0xbe860)
 336           REFCNT = 1
 337           FLAGS = (IOK,pIOK)
 338           IV = 42
 339
 340 This says C<$a> is an SV and that it is an RV.  That RV points to
 341 another SV which is a PVAV, an array.  The array has one element,
 342 element zero, which is another SV. The field C<FILL> above indicates
 343 the last element in the array, similar to C<$#$a>.
 344
 345 If C<$a> pointed to an array of two elements then we would see the
 346 following.
 347
 348         use Devel::Peek 'Dump';
 349         $a = [42,24];
 350         Dump $a;
 351
 352 The output:
 353
 354         SV = RV(0xf041c)
 355           REFCNT = 1
 356           FLAGS = (ROK)
 357           RV = 0xb2850
 358         SV = PVAV(0xbd448)
 359           REFCNT = 1
 360           FLAGS = ()
 361           IV = 0
 362           NV = 0
 363           ARRAY = 0xb2048
 364           ALLOC = 0xb2048
 365           FILL = 0
 366           MAX = 0
 367           ARYLEN = 0x0
 368           FLAGS = (REAL)
 369         Elt No. 0  0xb5658
 370         SV = IV(0xbe860)
 371           REFCNT = 1
 372           FLAGS = (IOK,pIOK)
 373           IV = 42
 374         Elt No. 1  0xb5680
 375         SV = IV(0xbe818)
 376           REFCNT = 1
 377           FLAGS = (IOK,pIOK)
 378           IV = 24
 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
 388         use Devel::Peek;
 389         $a = {hello=>42};
 390         Dump $a;
 391
 392 The output:
 393
 394         SV = RV(0x8177858) at 0x816a618
 395           REFCNT = 1
 396           FLAGS = (ROK)
 397           RV = 0x814fc10
 398           SV = PVHV(0x8167768) at 0x814fc10
 399             REFCNT = 1
 400             FLAGS = (SHAREKEYS)
 401             IV = 1
 402             NV = 0
 403             ARRAY = 0x816c5b8  (0:7, 1:1)
 404             hash quality = 100.0%
 405             KEYS = 1
 406             FILL = 1
 407             MAX = 7
 408             RITER = -1
 409             EITER = 0x0
 410             Elt "hello" HASH = 0xc8fd181b
 411             SV = IV(0x816c030) at 0x814fcf4
 412               REFCNT = 1
 413               FLAGS = (IOK,pIOK)
 414               IV = 42
 415
 416 This shows C<$a> is a reference pointing to an SV.  That SV is a PVHV, a
 417 hash. Fields RITER and EITER are used by C<L<each>>.
 418
 419 The "quality" of a hash is defined as the total number of comparisons needed
 420 to access every element once, relative to the expected number needed for a
 421 random hash. The value can go over 100%.
 422
 423 The total number of comparisons is equal to the sum of the squares of the
 424 number of entries in each bucket.  For a random hash of C<<n>> keys into
 425 C<<k>> buckets, the expected value is:
 426
 427                 n + n(n-1)/2k
 428
 429 =head2 Dumping a large array or hash
 430
 431 The C<Dump()> function, by default, dumps up to 4 elements from a
 432 toplevel array or hash.  This number can be increased by supplying a
 433 second argument to the function.
 434
 435         use Devel::Peek;
 436         $a = [10,11,12,13,14];
 437         Dump $a;
 438
 439 Notice that C<Dump()> prints only elements 10 through 13 in the above code.
 440 The following code will print all of the elements.
 441
 442         use Devel::Peek 'Dump';
 443         $a = [10,11,12,13,14];
 444         Dump $a, 5;
 445
 446 =head2 A reference to an SV which holds a C pointer
 447
 448 This is what you really need to know as an XS programmer, of course.  When
 449 an XSUB returns a pointer to a C structure that pointer is stored in an SV
 450 and a reference to that SV is placed on the XSUB stack.  So the output from
 451 an XSUB which uses something like the T_PTROBJ map might look something like
 452 this:
 453
 454         SV = RV(0xf381c)
 455           REFCNT = 1
 456           FLAGS = (ROK)
 457           RV = 0xb8ad8
 458         SV = PVMG(0xbb3c8)
 459           REFCNT = 1
 460           FLAGS = (OBJECT,IOK,pIOK)
 461           IV = 729160
 462           NV = 0
 463           PV = 0
 464           STASH = 0xc1d10       "CookBookB::Opaque"
 465
 466 This shows that we have an SV which is an RV.  That RV points at another
 467 SV.  In this case that second SV is a PVMG, a blessed scalar.  Because it is
 468 blessed it has the C<OBJECT> flag set.  Note that an SV which holds a C
 469 pointer also has the C<IOK> flag set.  The C<STASH> is set to the package
 470 name which this SV was blessed into.
 471
 472 The output from an XSUB which uses something like the T_PTRREF map, which
 473 doesn't bless the object, might look something like this:
 474
 475         SV = RV(0xf381c)
 476           REFCNT = 1
 477           FLAGS = (ROK)
 478           RV = 0xb8ad8
 479         SV = PVMG(0xbb3c8)
 480           REFCNT = 1
 481           FLAGS = (IOK,pIOK)
 482           IV = 729160
 483           NV = 0
 484           PV = 0
 485
 486 =head2 A reference to a subroutine
 487
 488 Looks like this:
 489
 490         SV = RV(0x798ec)
 491           REFCNT = 1
 492           FLAGS = (TEMP,ROK)
 493           RV = 0x1d453c
 494         SV = PVCV(0x1c768c)
 495           REFCNT = 2
 496           FLAGS = ()
 497           IV = 0
 498           NV = 0
 499           COMP_STASH = 0x31068  "main"
 500           START = 0xb20e0
 501           ROOT = 0xbece0
 502           XSUB = 0x0
 503           XSUBANY = 0
 504           GVGV::GV = 0x1d44e8   "MY" :: "top_targets"
 505           FILE = "(eval 5)"
 506           DEPTH = 0
 507           PADLIST = 0x1c9338
 508
 509 This shows that
 510
 511 =over 4
 512
 513 =item *
 514
 515 the subroutine is not an XSUB (since C<START> and C<ROOT> are
 516 non-zero, and C<XSUB> is zero);
 517
 518 =item *
 519
 520 that it was compiled in the package C<main>;
 521
 522 =item *
 523
 524 under the name C<MY::top_targets>;
 525
 526 =item *
 527
 528 inside a 5th eval in the program;
 529
 530 =item *
 531
 532 it is not currently executed (see C<DEPTH>);
 533
 534 =item *
 535
 536 it has no prototype (C<PROTOTYPE> field is missing).
 537
 538 =back
 539
 540 =head1 EXPORTS
 541
 542 C<Dump>, C<mstat>, C<DeadCode>, C<DumpArray>, C<DumpWithOP> and
 543 C<DumpProg>, C<fill_mstats>, C<mstats_fillhash>, C<mstats2hash> by
 544 default. Additionally available C<SvREFCNT>, C<SvREFCNT_inc> and
 545 C<SvREFCNT_dec>.
 546
 547 =head1 BUGS
 548
 549 Readers have been known to skip important parts of L<perlguts>, causing much
 550 frustration for all.
 551
 552 =head1 AUTHOR
 553
 554 Ilya Zakharevich        ilya@math.ohio-state.edu
 555
 556 Copyright (c) 1995-98 Ilya Zakharevich. All rights reserved.
 557 This program is free software; you can redistribute it and/or
 558 modify it under the same terms as Perl itself.
 559
 560 Author of this software makes no claim whatsoever about suitability,
 561 reliability, edability, editability or usability of this product, and
 562 should not be kept liable for any damage resulting from the use of
 563 it. If you can use it, you are in luck, if not, I should not be kept
 564 responsible. Keep a handy copy of your backup tape at hand.
 565
 566 =head1 SEE ALSO
 567
 568 L<perlguts>, and L<perlguts>, again.
 569
 570 =cut