1# Devel::Peek - A data debugging tool for the XS programmer 2# The documentation is after the __END__ 3 4package Devel::Peek; 5 6$VERSION = '1.04'; 7$XS_VERSION = $VERSION; 8$VERSION = eval $VERSION; 9 10require Exporter; 11use 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 19XSLoader::load 'Devel::Peek'; 20 21sub 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 41sub 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 49sub 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 671; 68__END__ 69 70=head1 NAME 71 72Devel::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 86Devel::Peek contains functions which allows raw Perl datatypes to be 87manipulated from a Perl script. This is used by those who do XS programming 88to check that the data they are sending from C to Perl looks as they think 89it should look. The trick, then, is to know what the raw datatype is 90supposed to look like when it gets to Perl. This document offers some tips 91and hints to describe good and bad raw data. 92 93It is very possible that this document will fall far short of being useful 94to the casual reader. The reader is expected to understand the material in 95the first few sections of L<perlguts>. 96 97Devel::Peek supplies a C<Dump()> function which can dump a raw Perl 98datatype, and C<mstat("marker")> function to report on memory usage 99(if perl is compiled with corresponding option). The function 100DeadCode() provides statistics on the data "frozen" into inactive 101C<CV>. Devel::Peek also supplies C<SvREFCNT()>, C<SvREFCNT_inc()>, and 102C<SvREFCNT_dec()> which can query, increment, and decrement reference 103counts on SVs. This document will take a passive, and safe, approach 104to data debugging and for that it will describe only the C<Dump()> 105function. 106 107Function C<DumpArray()> allows dumping of multiple values (useful when you 108need to analyze returns of functions). 109 110The global variable $Devel::Peek::pv_limit can be set to limit the 111number of character printed in various string values. Setting it to 0 112means no limit. 113 114If C<use Devel::Peek> directive has a C<:opd=FLAGS> argument, 115this switches on debugging of opcode dispatch. C<FLAGS> should be a 116combination of C<s>, C<t>, and C<P> (see B<-D> flags in L<perlrun>). 117C<:opd> is a shortcut for C<:opd=st>. 118 119=head2 Runtime debugging 120 121C<CvGV($cv)> return one of the globs associated to a subroutine reference $cv. 122 123debug_flags() returns a string representation of C<$^D> (similar to 124what is allowed for B<-D> flag). When called with a numeric argument, 125sets $^D to the corresponding value. When called with an argument of 126the form C<"flags-flags">, set on/off bits of C<$^D> corresponding to 127letters before/after C<->. (The returned value is for C<$^D> before 128the modification.) 129 130runops_debug() returns true if the current I<opcode dispatcher> is the 131debugging one. When called with an argument, switches to debugging or 132non-debugging dispatcher depending on the argument (active for 133newly-entered subs/etc only). (The returned value is for the dispatcher before the modification.) 134 135=head2 Memory footprint debugging 136 137When perl is compiled with support for memory footprint debugging 138(default with Perl's malloc()), Devel::Peek provides an access to this API. 139 140Use mstat() function to emit a memory state statistic to the terminal. 141For more information on the format of output of mstat() see 142L<perldebguts/Using C<$ENV{PERL_DEBUG_MSTATS}>>. 143 144Three additional functions allow access to this statistic from Perl. 145First, use C<mstats_fillhash(%hash)> to get the information contained 146in 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 151Two additional fields C<free>, C<used> contain array references which 152provide per-bucket count of free and used chunks. Two other fields 153C<mem_size>, C<available_size> contain array references which provide 154the information about the allocated size and usable size of chunks in 155each bucket. Again, see L<perldebguts/Using C<$ENV{PERL_DEBUG_MSTATS}>> 156for details. 157 158Keep in mind that only the first several "odd-numbered" buckets are 159used, so the information on size of the "odd-numbered" buckets which are 160not used is probably meaningless. 161 162The information in 163 164 mem_size available_size minbucket nbuckets 165 166is the property of a particular build of perl, and does not depend on 167the current process. If you do not provide the optional argument to 168the functions mstats_fillhash(), fill_mstats(), mstats2hash(), then 169the information in fields C<mem_size>, C<available_size> is not 170updated. 171 172C<fill_mstats($buf)> is a much cheaper call (both speedwise and 173memory-wise) which collects the statistic into $buf in 174machine-readable form. At a later moment you may need to call 175C<mstats2hash($buf, %hash)> to use this information to fill %hash. 176 177All three APIs C<fill_mstats($buf)>, C<mstats_fillhash(%hash)>, and 178C<mstats2hash($buf, %hash)> are designed to allocate no memory if used 179I<the second time> on the same $buf and/or %hash. 180 181So, 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 198The following examples don't attempt to show everything as that would be a 199monumental task, and, frankly, we don't want this manpage to be an internals 200document for Perl. The examples do demonstrate some basics of the raw Perl 201datatypes, and should suffice to get most determined people on their way. 202There are no guidewires or safety nets, nor blazed trails, so be prepared to 203travel alone from this point and on and, if at all possible, don't fall into 204the quicksand (it's bad for business). 205 206Oh, one final bit of advice: take L<perlguts> with you. When you return we 207expect to see it well-thumbed. 208 209=head2 A simple scalar string 210 211Let's begin by looking a simple scalar which is holding a string. 212 213 use Devel::Peek; 214 $a = "hello"; 215 Dump $a; 216 217The 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 227This says C<$a> is an SV, a scalar. The scalar is a PVIV, a string. 228Its reference count is 1. It has the C<POK> flag set, meaning its 229current PV field is valid. Because POK is set we look at the PV item 230to see what is in the scalar. The \0 at the end indicate that this 231PV is properly NUL-terminated. 232If the FLAGS had been IOK we would look 233at the IV item. CUR indicates the number of characters in the PV. 234LEN indicates the number of bytes requested for the PV (one more than 235CUR, in this case, because LEN includes an extra byte for the 236end-of-string marker). 237 238=head2 A simple scalar number 239 240If the scalar contains a number the raw SV will be leaner. 241 242 use Devel::Peek; 243 $a = 42; 244 Dump $a; 245 246The output: 247 248 SV = IV(0xbc818) 249 REFCNT = 1 250 FLAGS = (IOK,pIOK) 251 IV = 42 252 253This says C<$a> is an SV, a scalar. The scalar is an IV, a number. Its 254reference count is 1. It has the C<IOK> flag set, meaning it is currently 255being evaluated as a number. Because IOK is set we look at the IV item to 256see what is in the scalar. 257 258=head2 A simple scalar with an extra reference 259 260If 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 267The output: 268 269 SV = IV(0xbe860) 270 REFCNT = 2 271 FLAGS = (IOK,pIOK) 272 IV = 42 273 274Notice that this example differs from the previous example only in its 275reference count. Compare this to the next example, where we dump C<$b> 276instead of C<$a>. 277 278=head2 A reference to a simple scalar 279 280This 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 287The 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 298Starting from the top, this says C<$b> is an SV. The scalar is an RV, a 299reference. It has the C<ROK> flag set, meaning it is a reference. Because 300ROK is set we have an RV item rather than an IV or PV. Notice that Dump 301follows the reference and shows us what C<$b> was referencing. We see the 302same C<$a> that we found in the previous example. 303 304Note that the value of C<RV> coincides with the numbers we see when we 305stringify $b. The addresses inside RV() and IV() are addresses of 306C<X***> structure which holds the current state of an C<SV>. This 307address may change during lifetime of an SV. 308 309=head2 A reference to an array 310 311This shows what a reference to an array looks like. 312 313 use Devel::Peek; 314 $a = [42]; 315 Dump $a; 316 317The 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 340This says C<$a> is an SV and that it is an RV. That RV points to 341another SV which is a PVAV, an array. The array has one element, 342element zero, which is another SV. The field C<FILL> above indicates 343the last element in the array, similar to C<$#$a>. 344 345If C<$a> pointed to an array of two elements then we would see the 346following. 347 348 use Devel::Peek 'Dump'; 349 $a = [42,24]; 350 Dump $a; 351 352The 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 380Note that C<Dump> will not report I<all> the elements in the array, 381only several first (depending on how deep it already went into the 382report tree). 383 384=head2 A reference to a hash 385 386The following shows the raw form of a reference to a hash. 387 388 use Devel::Peek; 389 $a = {hello=>42}; 390 Dump $a; 391 392The 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 416This shows C<$a> is a reference pointing to an SV. That SV is a PVHV, a 417hash. Fields RITER and EITER are used by C<L<each>>. 418 419The "quality" of a hash is defined as the total number of comparisons needed 420to access every element once, relative to the expected number needed for a 421random hash. The value can go over 100%. 422 423The total number of comparisons is equal to the sum of the squares of the 424number of entries in each bucket. For a random hash of C<<n>> keys into 425C<<k>> buckets, the expected value is: 426 427 n + n(n-1)/2k 428 429=head2 Dumping a large array or hash 430 431The C<Dump()> function, by default, dumps up to 4 elements from a 432toplevel array or hash. This number can be increased by supplying a 433second argument to the function. 434 435 use Devel::Peek; 436 $a = [10,11,12,13,14]; 437 Dump $a; 438 439Notice that C<Dump()> prints only elements 10 through 13 in the above code. 440The 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 448This is what you really need to know as an XS programmer, of course. When 449an XSUB returns a pointer to a C structure that pointer is stored in an SV 450and a reference to that SV is placed on the XSUB stack. So the output from 451an XSUB which uses something like the T_PTROBJ map might look something like 452this: 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 466This shows that we have an SV which is an RV. That RV points at another 467SV. In this case that second SV is a PVMG, a blessed scalar. Because it is 468blessed it has the C<OBJECT> flag set. Note that an SV which holds a C 469pointer also has the C<IOK> flag set. The C<STASH> is set to the package 470name which this SV was blessed into. 471 472The output from an XSUB which uses something like the T_PTRREF map, which 473doesn'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 488Looks 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 509This shows that 510 511=over 4 512 513=item * 514 515the subroutine is not an XSUB (since C<START> and C<ROOT> are 516non-zero, and C<XSUB> is zero); 517 518=item * 519 520that it was compiled in the package C<main>; 521 522=item * 523 524under the name C<MY::top_targets>; 525 526=item * 527 528inside a 5th eval in the program; 529 530=item * 531 532it is not currently executed (see C<DEPTH>); 533 534=item * 535 536it has no prototype (C<PROTOTYPE> field is missing). 537 538=back 539 540=head1 EXPORTS 541 542C<Dump>, C<mstat>, C<DeadCode>, C<DumpArray>, C<DumpWithOP> and 543C<DumpProg>, C<fill_mstats>, C<mstats_fillhash>, C<mstats2hash> by 544default. Additionally available C<SvREFCNT>, C<SvREFCNT_inc> and 545C<SvREFCNT_dec>. 546 547=head1 BUGS 548 549Readers have been known to skip important parts of L<perlguts>, causing much 550frustration for all. 551 552=head1 AUTHOR 553 554Ilya Zakharevich ilya@math.ohio-state.edu 555 556Copyright (c) 1995-98 Ilya Zakharevich. All rights reserved. 557This program is free software; you can redistribute it and/or 558modify it under the same terms as Perl itself. 559 560Author of this software makes no claim whatsoever about suitability, 561reliability, edability, editability or usability of this product, and 562should not be kept liable for any damage resulting from the use of 563it. If you can use it, you are in luck, if not, I should not be kept 564responsible. Keep a handy copy of your backup tape at hand. 565 566=head1 SEE ALSO 567 568L<perlguts>, and L<perlguts>, again. 569 570=cut 571