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