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