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