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