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