[Summary view] [Print] [Text view]

   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