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