home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / perl_ste.zip / Devel / Peek.pm
Text File  |  1997-11-28  |  11KB  |  415 lines
  1. package Devel::Peek;
  2.  
  3. =head1 NAME
  4.  
  5. Devel::Peek - A data debugging tool for the XS programmer
  6.  
  7. =head1 SYNOPSIS
  8.  
  9.         use Devel::Peek;
  10.         Dump( $a );
  11.         Dump( $a, 5 );
  12.         DumpArray( 5, $a, $b, ... );
  13.     mstat "Point 5";
  14.  
  15. =head1 DESCRIPTION
  16.  
  17. Devel::Peek contains functions which allows raw Perl datatypes to be
  18. manipulated from a Perl script.  This is used by those who do XS programming
  19. to check that the data they are sending from C to Perl looks as they think
  20. it should look.  The trick, then, is to know what the raw datatype is
  21. supposed to look like when it gets to Perl.  This document offers some tips
  22. and hints to describe good and bad raw data.
  23.  
  24. It is very possible that this document will fall far short of being useful
  25. to the casual reader.  The reader is expected to understand the material in
  26. the first few sections of L<perlguts>.
  27.  
  28. Devel::Peek supplies a C<Dump()> function which can dump a raw Perl
  29. datatype, and C<mstat("marker")> function to report on memory usage
  30. (if perl is compiled with corresponding option).  The function
  31. DeadCode() provides statistics on the data "frozen" into inactive
  32. C<CV>.  Devel::Peek also supplies C<SvREFCNT()>, C<SvREFCNT_inc()>, and
  33. C<SvREFCNT_dec()> which can query, increment, and decrement reference
  34. counts on SVs.  This document will take a passive, and safe, approach
  35. to data debugging and for that it will describe only the C<Dump()>
  36. function.
  37.  
  38. Function C<DumpArray()> allows dumping of multiple values (useful when you
  39. need to analize returns of functions).
  40.  
  41. =head1 EXAMPLES
  42.  
  43. The following examples don't attempt to show everything as that would be a
  44. monumental task, and, frankly, we don't want this manpage to be an internals
  45. document for Perl.  The examples do demonstrate some basics of the raw Perl
  46. datatypes, and should suffice to get most determined people on their way.
  47. There are no guidewires or safety nets, nor blazed trails, so be prepared to
  48. travel alone from this point and on and, if at all possible, don't fall into
  49. the quicksand (it's bad for business).
  50.  
  51. Oh, one final bit of advice: take L<perlguts> with you.  When you return we
  52. expect to see it well-thumbed.
  53.  
  54. =head2 A simple scalar string
  55.  
  56. Let's begin by looking a simple scalar which is holding a string.
  57.  
  58.         use Devel::Peek 'Dump';
  59.         $a = "hello";
  60.         Dump $a;
  61.  
  62. The output:
  63.  
  64.         SV = PVIV(0xbc288)
  65.           REFCNT = 1
  66.           FLAGS = (POK,pPOK)
  67.           IV = 0
  68.           PV = 0xb2048 "hello"
  69.           CUR = 5
  70.           LEN = 6
  71.  
  72. This says C<$a> is an SV, a scalar.  The scalar is a PVIV, a string.
  73. Its reference count is 1.  It has the C<POK> flag set, meaning its
  74. current PV field is valid.  Because POK is set we look at the PV item
  75. to see what is in the scalar.  If the FLAGS had been IOK we would look
  76. at the IV item.  CUR indicates the number of characters in the PV.
  77. LEN indicates the number of bytes requested for the PV (one more than
  78. CUR, in this case, because LEN includes an extra byte for the
  79. end-of-string marker).
  80.  
  81. =head2 A simple scalar number
  82.  
  83. If the scalar contains a number the raw SV will be leaner.
  84.  
  85.         use Devel::Peek 'Dump';
  86.         $a = 42;
  87.         Dump $a;
  88.  
  89. The output:
  90.  
  91.         SV = IV(0xbc818)
  92.           REFCNT = 1
  93.           FLAGS = (IOK,pIOK)
  94.           IV = 42
  95.  
  96. This says C<$a> is an SV, a scalar.  The scalar is an IV, a number.  Its
  97. reference count is 1.  It has the C<IOK> flag set, meaning it is currently
  98. being evaluated as a number.  Because IOK is set we look at the IV item to
  99. see what is in the scalar.
  100.  
  101. =head2 A simple scalar with an extra reference
  102.  
  103. If the scalar from the previous example had an extra reference:
  104.  
  105.         use Devel::Peek 'Dump';
  106.         $a = 42;
  107.         $b = \$a;
  108.         Dump $a;
  109.  
  110. The output:
  111.  
  112.         SV = IV(0xbe860)
  113.           REFCNT = 2
  114.           FLAGS = (IOK,pIOK)
  115.           IV = 42
  116.  
  117. Notice that this example differs from the previous example only in its
  118. reference count.  Compare this to the next example, where we dump C<$b>
  119. instead of C<$a>.
  120.  
  121. =head2 A reference to a simple scalar
  122.  
  123. This shows what a reference looks like when it references a simple scalar.
  124.  
  125.         use Devel::Peek 'Dump';
  126.         $a = 42;
  127.         $b = \$a;
  128.         Dump $b;
  129.  
  130. The output:
  131.  
  132.         SV = RV(0xf041c)
  133.           REFCNT = 1
  134.           FLAGS = (ROK)
  135.           RV = 0xbab08
  136.         SV = IV(0xbe860)
  137.           REFCNT = 2
  138.           FLAGS = (IOK,pIOK)
  139.           IV = 42
  140.  
  141. Starting from the top, this says C<$b> is an SV.  The scalar is an RV, a
  142. reference.  It has the C<ROK> flag set, meaning it is a reference.  Because
  143. ROK is set we have an RV item rather than an IV or PV.  Notice that Dump
  144. follows the reference and shows us what C<$b> was referencing.  We see the
  145. same C<$a> that we found in the previous example.
  146.  
  147. Note that the value of C<RV> coincides with the numbers we see when we
  148. stringify $b. The addresses inside RV() and IV() are addresses of
  149. C<X***> structure which holds the current state of an C<SV>. This
  150. address may change during lifetime of an SV.
  151.  
  152. =head2 A reference to an array
  153.  
  154. This shows what a reference to an array looks like.
  155.  
  156.         use Devel::Peek 'Dump';
  157.         $a = [42];
  158.         Dump $a;
  159.  
  160. The output:
  161.  
  162.         SV = RV(0xf041c)
  163.           REFCNT = 1
  164.           FLAGS = (ROK)
  165.           RV = 0xb2850
  166.         SV = PVAV(0xbd448)
  167.           REFCNT = 1
  168.           FLAGS = ()
  169.           IV = 0
  170.           NV = 0
  171.           ARRAY = 0xb2048
  172.           ALLOC = 0xb2048
  173.           FILL = 0
  174.           MAX = 0
  175.           ARYLEN = 0x0
  176.           FLAGS = (REAL)
  177.         Elt No. 0 0xb5658
  178.         SV = IV(0xbe860)
  179.           REFCNT = 1
  180.           FLAGS = (IOK,pIOK)
  181.           IV = 42
  182.  
  183. This says C<$a> is an SV and that it is an RV.  That RV points to
  184. another SV which is a PVAV, an array.  The array has one element,
  185. element zero, which is another SV. The field C<FILL> above indicates
  186. the last element in the array, similar to C<$#$a>.
  187.  
  188. If C<$a> pointed to an array of two elements then we would see the
  189. following.
  190.  
  191.         use Devel::Peek 'Dump';
  192.         $a = [42,24];
  193.         Dump $a;
  194.  
  195. The output:
  196.  
  197.         SV = RV(0xf041c)
  198.           REFCNT = 1
  199.           FLAGS = (ROK)
  200.           RV = 0xb2850
  201.         SV = PVAV(0xbd448)
  202.           REFCNT = 1
  203.           FLAGS = ()
  204.           IV = 0
  205.           NV = 0
  206.           ARRAY = 0xb2048
  207.           ALLOC = 0xb2048
  208.           FILL = 0
  209.           MAX = 0
  210.           ARYLEN = 0x0
  211.           FLAGS = (REAL)
  212.         Elt No. 0  0xb5658
  213.         SV = IV(0xbe860)
  214.           REFCNT = 1
  215.           FLAGS = (IOK,pIOK)
  216.           IV = 42
  217.         Elt No. 1  0xb5680
  218.         SV = IV(0xbe818)
  219.           REFCNT = 1
  220.           FLAGS = (IOK,pIOK)
  221.           IV = 24
  222.  
  223. Note that C<Dump> will not report I<all> the elements in the array,
  224. only several first (depending on how deep it already went into the
  225. report tree).
  226.  
  227. =head2 A reference to a hash
  228.  
  229. The following shows the raw form of a reference to a hash.
  230.  
  231.         use Devel::Peek 'Dump';
  232.         $a = {hello=>42};
  233.         Dump $a;
  234.  
  235. The output:
  236.  
  237.         SV = RV(0xf041c)
  238.           REFCNT = 1
  239.           FLAGS = (ROK)
  240.           RV = 0xb2850
  241.         SV = PVHV(0xbd448)
  242.           REFCNT = 1
  243.           FLAGS = ()
  244.           IV = 1
  245.           NV = 0
  246.           ARRAY = 0xbd748
  247.           KEYS = 1
  248.           FILL = 1
  249.           MAX = 7
  250.           RITER = -1
  251.           EITER = 0x0
  252.         Elt "hello" => 0xbaaf0
  253.         SV = IV(0xbe860)
  254.           REFCNT = 1
  255.           FLAGS = (IOK,pIOK)
  256.           IV = 42
  257.  
  258. This shows C<$a> is a reference pointing to an SV.  That SV is a PVHV, a
  259. hash. Fields RITER and EITER are used by C<L<each>>.
  260.  
  261. =head2 Dumping a large array or hash
  262.  
  263. The C<Dump()> function, by default, dumps up to 4 elements from a
  264. toplevel array or hash.  This number can be increased by supplying a
  265. second argument to the function.
  266.  
  267.         use Devel::Peek 'Dump';
  268.         $a = [10,11,12,13,14];
  269.         Dump $a;
  270.  
  271. Notice that C<Dump()> prints only elements 10 through 13 in the above code.
  272. The following code will print all of the elements.
  273.  
  274.         use Devel::Peek 'Dump';
  275.         $a = [10,11,12,13,14];
  276.         Dump $a, 5;
  277.  
  278. =head2 A reference to an SV which holds a C pointer
  279.  
  280. This is what you really need to know as an XS programmer, of course.  When
  281. an XSUB returns a pointer to a C structure that pointer is stored in an SV
  282. and a reference to that SV is placed on the XSUB stack.  So the output from
  283. an XSUB which uses something like the T_PTROBJ map might look something like
  284. this:
  285.  
  286.         SV = RV(0xf381c)
  287.           REFCNT = 1
  288.           FLAGS = (ROK)
  289.           RV = 0xb8ad8
  290.         SV = PVMG(0xbb3c8)
  291.           REFCNT = 1
  292.           FLAGS = (OBJECT,IOK,pIOK)
  293.           IV = 729160
  294.           NV = 0
  295.           PV = 0
  296.           STASH = 0xc1d10       "CookBookB::Opaque"
  297.  
  298. This shows that we have an SV which is an RV.  That RV points at another
  299. SV.  In this case that second SV is a PVMG, a blessed scalar.  Because it is
  300. blessed it has the C<OBJECT> flag set.  Note that an SV which holds a C
  301. pointer also has the C<IOK> flag set.  The C<STASH> is set to the package
  302. name which this SV was blessed into.
  303.  
  304. The output from an XSUB which uses something like the T_PTRREF map, which
  305. doesn't bless the object, might look something like this:
  306.  
  307.         SV = RV(0xf381c)
  308.           REFCNT = 1
  309.           FLAGS = (ROK)
  310.           RV = 0xb8ad8
  311.         SV = PVMG(0xbb3c8)
  312.           REFCNT = 1
  313.           FLAGS = (IOK,pIOK)
  314.           IV = 729160
  315.           NV = 0
  316.           PV = 0
  317.  
  318. =head2 A reference to a subroutine
  319.  
  320. Looks like this:
  321.  
  322.     SV = RV(0x798ec)
  323.       REFCNT = 1
  324.       FLAGS = (TEMP,ROK)
  325.       RV = 0x1d453c
  326.     SV = PVCV(0x1c768c)
  327.       REFCNT = 2
  328.       FLAGS = ()
  329.       IV = 0
  330.       NV = 0
  331.       COMP_STASH = 0x31068  "main"
  332.       START = 0xb20e0
  333.       ROOT = 0xbece0
  334.       XSUB = 0x0
  335.       XSUBANY = 0
  336.       GVGV::GV = 0x1d44e8   "MY" :: "top_targets"
  337.       FILEGV = 0x1fab74     "_<(eval 5)"
  338.       DEPTH = 0
  339.       PADLIST = 0x1c9338
  340.  
  341. This shows that 
  342.  
  343. =over
  344.  
  345. =item
  346.  
  347. the subroutine is not an XSUB (since C<START> and C<ROOT> are
  348. non-zero, and C<XSUB> is zero);
  349.  
  350. =item
  351.  
  352. that it was compiled in the package C<main>;
  353.  
  354. =item
  355.  
  356. under the name C<MY::top_targets>; 
  357.  
  358. =item
  359.  
  360. inside a 5th eval in the program;
  361.  
  362. =item
  363.  
  364. it is not currently executed (see C<DEPTH>);
  365.  
  366.  
  367. =item
  368.  
  369. it has no prototype (C<PROTOTYPE> field is missing).
  370.  
  371. =over
  372.  
  373. =head1 EXPORTS
  374.  
  375. C<Peek>, C<mstats>, C<DeadCode> by default. Additionally available C<SvREFCNT>,
  376. C<SvREFCNT_inc>, C<SvREFCNT_dec>.
  377.  
  378. =head1 BUGS
  379.  
  380. Readers have been known to skip important parts of L<perlguts>, causing much
  381. frustration for all.
  382.  
  383. =head1 SEE ALSO
  384.  
  385. L<perlguts>, and L<perlguts>, again.
  386.  
  387. =cut
  388.  
  389. require Exporter;
  390. require DynaLoader;
  391.  
  392. @ISA = qw(Exporter DynaLoader);
  393. # Items to export into callers namespace by default. Note: do not export
  394. # names by default without a very good reason. Use EXPORT_OK instead.
  395. # Do not simply export all your public functions/methods/constants.
  396. @EXPORT = qw(
  397.     Dump mstat DeadCode DumpArray
  398. );
  399. # Other items we are prepared to export if requested
  400. @EXPORT_OK = qw(
  401.         Dump SvREFCNT SvREFCNT_inc SvREFCNT_dec mstat DeadCode DumpArray
  402. );
  403. %EXPORT_TAGS = ('ALL' => \@EXPORT_OK);
  404.  
  405. $VERSION = $VERSION = 0.84;
  406.  
  407. bootstrap Devel::Peek;
  408.  
  409. # Preloaded methods go here.
  410.  
  411. # Autoload methods go after __END__, and are processed by the autosplit program.
  412.  
  413. 1;
  414. __END__
  415.