1Devel::Peek(3pm) Perl Programmers Reference Guide Devel::Peek(3pm)
2
6 Devel::Peek - A data debugging tool for the XS programmer
7
9 use Devel::Peek;
10 Dump( $a );
11 Dump( $a, 5 );
12 DumpArray( 5, $a, $b, ... );
13 mstat "Point 5";
14 use Devel::Peek ':opd=st';
16
18 Devel::Peek contains functions which allows raw Perl datatypes to be
19 manipulated from a Perl script. This is used by those who do XS pro‐
20 gramming to check that the data they are sending from C to Perl looks
21 as they think it should look. The trick, then, is to know what the raw
22 datatype is supposed to look like when it gets to Perl. This document
23 offers some tips and hints to describe good and bad raw data.
24 It is very possible that this document will fall far short of being
26 useful to the casual reader. The reader is expected to understand the
27 material in the first few sections of perlguts.
28 Devel::Peek supplies a "Dump()" function which can dump a raw Perl
30 datatype, and "mstat("marker")" function to report on memory usage (if
31 perl is compiled with corresponding option). The function DeadCode()
32 provides statistics on the data "frozen" into inactive "CV".
33 Devel::Peek also supplies "SvREFCNT()", "SvREFCNT_inc()", and "SvRE‐
34 FCNT_dec()" which can query, increment, and decrement reference counts
35 on SVs. This document will take a passive, and safe, approach to data
36 debugging and for that it will describe only the "Dump()" function.
37 Function "DumpArray()" allows dumping of multiple values (useful when
39 you need to analyze returns of functions).
40 The global variable $Devel::Peek::pv_limit can be set to limit the num‐
42 ber of character printed in various string values. Setting it to 0
43 means no limit.
44 If "use Devel::Peek" directive has a ":opd=FLAGS" argument, this
46 switches on debugging of opcode dispatch. "FLAGS" should be a combina‐
47 tion of "s", "t", and "P" (see -D flags in perlrun). ":opd" is a
48 shortcut for ":opd=st".
49 Runtime debugging
51 "CvGV($cv)" return one of the globs associated to a subroutine refer‐
53 ence $cv.
54 debug_flags() returns a string representation of $^D (similar to what
56 is allowed for -D flag). When called with a numeric argument, sets $^D
57 to the corresponding value. When called with an argument of the form
58 "flags-flags", set on/off bits of $^D corresponding to letters
59 before/after "-". (The returned value is for $^D before the modifica‐
60 tion.)
61 runops_debug() returns true if the current opcode dispatcher is the
63 debugging one. When called with an argument, switches to debugging or
64 non-debugging dispatcher depending on the argument (active for newly-
65 entered subs/etc only). (The returned value is for the dispatcher
66 before the modification.)
67 Memory footprint debugging
69 When perl is compiled with support for memory footprint debugging
71 (default with Perl's malloc()), Devel::Peek provides an access to this
72 API.
73 Use mstat() function to emit a memory state statistic to the terminal.
75 For more information on the format of output of mstat() see "Using
76 $ENV{PERL_DEBUG_MSTATS}" in perldebguts.
77 Three additional functions allow access to this statistic from Perl.
79 First, use "mstats_fillhash(%hash)" to get the information contained in
80 the output of mstat() into %hash. The field of this hash are
81 minbucket nbuckets sbrk_good sbrk_slack sbrked_remains sbrks start_slack
83 topbucket topbucket_ev topbucket_odd total total_chain total_sbrk totfree
84 Two additional fields "free", "used" contain array references which
86 provide per-bucket count of free and used chunks. Two other fields
87 "mem_size", "available_size" contain array references which provide the
88 information about the allocated size and usable size of chunks in each
89 bucket. Again, see "Using $ENV{PERL_DEBUG_MSTATS}" in perldebguts for
90 details.
91 Keep in mind that only the first several "odd-numbered" buckets are
93 used, so the information on size of the "odd-numbered" buckets which
94 are not used is probably meaningless.
95 The information in
97 mem_size available_size minbucket nbuckets
99 is the property of a particular build of perl, and does not depend on
101 the current process. If you do not provide the optional argument to
102 the functions mstats_fillhash(), fill_mstats(), mstats2hash(), then the
103 information in fields "mem_size", "available_size" is not updated.
104 "fill_mstats($buf)" is a much cheaper call (both speedwise and mem‐
106 ory-wise) which collects the statistic into $buf in machine-readable
107 form. At a later moment you may need to call "mstats2hash($buf,
108 %hash)" to use this information to fill %hash.
109 All three APIs "fill_mstats($buf)", "mstats_fillhash(%hash)", and
111 "mstats2hash($buf, %hash)" are designed to allocate no memory if used
112 the second time on the same $buf and/or %hash.
113 So, if you want to collect memory info in a cycle, you may call
115 $#buf = 999;
117 fill_mstats($_) for @buf;
118 mstats_fillhash(%report, 1); # Static info too
119 foreach (@buf) {
121 # Do something...
122 fill_mstats $_; # Collect statistic
123 }
124 foreach (@buf) {
125 mstats2hash($_, %report); # Preserve static info
126 # Do something with %report
127 }
128
130 The following examples don't attempt to show everything as that would
131 be a monumental task, and, frankly, we don't want this manpage to be an
132 internals document for Perl. The examples do demonstrate some basics
133 of the raw Perl datatypes, and should suffice to get most determined
134 people on their way. There are no guidewires or safety nets, nor
135 blazed trails, so be prepared to travel alone from this point and on
136 and, if at all possible, don't fall into the quicksand (it's bad for
137 business).
138 Oh, one final bit of advice: take perlguts with you. When you return
140 we expect to see it well-thumbed.
141 A simple scalar string
143 Let's begin by looking a simple scalar which is holding a string.
145 use Devel::Peek;
147 $a = "hello";
148 Dump $a;
149 The output:
151 SV = PVIV(0xbc288)
153 REFCNT = 1
154 FLAGS = (POK,pPOK)
155 IV = 0
156 PV = 0xb2048 "hello"\0
157 CUR = 5
158 LEN = 6
159 This says $a is an SV, a scalar. The scalar is a PVIV, a string. Its
161 reference count is 1. It has the "POK" flag set, meaning its current
162 PV field is valid. Because POK is set we look at the PV item to see
163 what is in the scalar. The \0 at the end indicate that this PV is
164 properly NUL-terminated. If the FLAGS had been IOK we would look at
165 the IV item. CUR indicates the number of characters in the PV. LEN
166 indicates the number of bytes requested for the PV (one more than CUR,
167 in this case, because LEN includes an extra byte for the end-of-string
168 marker).
169 A simple scalar number
171 If the scalar contains a number the raw SV will be leaner.
173 use Devel::Peek;
175 $a = 42;
176 Dump $a;
177 The output:
179 SV = IV(0xbc818)
181 REFCNT = 1
182 FLAGS = (IOK,pIOK)
183 IV = 42
184 This says $a is an SV, a scalar. The scalar is an IV, a number. Its
186 reference count is 1. It has the "IOK" flag set, meaning it is cur‐
187 rently being evaluated as a number. Because IOK is set we look at the
188 IV item to see what is in the scalar.
189 A simple scalar with an extra reference
191 If the scalar from the previous example had an extra reference:
193 use Devel::Peek;
195 $a = 42;
196 $b = \$a;
197 Dump $a;
198 The output:
200 SV = IV(0xbe860)
202 REFCNT = 2
203 FLAGS = (IOK,pIOK)
204 IV = 42
205 Notice that this example differs from the previous example only in its
207 reference count. Compare this to the next example, where we dump $b
208 instead of $a.
209 A reference to a simple scalar
211 This shows what a reference looks like when it references a simple
213 scalar.
214 use Devel::Peek;
216 $a = 42;
217 $b = \$a;
218 Dump $b;
219 The output:
221 SV = RV(0xf041c)
223 REFCNT = 1
224 FLAGS = (ROK)
225 RV = 0xbab08
226 SV = IV(0xbe860)
227 REFCNT = 2
228 FLAGS = (IOK,pIOK)
229 IV = 42
230 Starting from the top, this says $b is an SV. The scalar is an RV, a
232 reference. It has the "ROK" flag set, meaning it is a reference.
233 Because ROK is set we have an RV item rather than an IV or PV. Notice
234 that Dump follows the reference and shows us what $b was referencing.
235 We see the same $a that we found in the previous example.
236 Note that the value of "RV" coincides with the numbers we see when we
238 stringify $b. The addresses inside RV() and IV() are addresses of
239 "X***" structure which holds the current state of an "SV". This address
240 may change during lifetime of an SV.
241 A reference to an array
243 This shows what a reference to an array looks like.
245 use Devel::Peek;
247 $a = [42];
248 Dump $a;
249 The output:
251 SV = RV(0xf041c)
253 REFCNT = 1
254 FLAGS = (ROK)
255 RV = 0xb2850
256 SV = PVAV(0xbd448)
257 REFCNT = 1
258 FLAGS = ()
259 IV = 0
260 NV = 0
261 ARRAY = 0xb2048
262 ALLOC = 0xb2048
263 FILL = 0
264 MAX = 0
265 ARYLEN = 0x0
266 FLAGS = (REAL)
267 Elt No. 0 0xb5658
268 SV = IV(0xbe860)
269 REFCNT = 1
270 FLAGS = (IOK,pIOK)
271 IV = 42
272 This says $a is an SV and that it is an RV. That RV points to another
274 SV which is a PVAV, an array. The array has one element, element zero,
275 which is another SV. The field "FILL" above indicates the last element
276 in the array, similar to "$#$a".
277 If $a pointed to an array of two elements then we would see the follow‐
279 ing.
280 use Devel::Peek 'Dump';
282 $a = [42,24];
283 Dump $a;
284 The output:
286 SV = RV(0xf041c)
288 REFCNT = 1
289 FLAGS = (ROK)
290 RV = 0xb2850
291 SV = PVAV(0xbd448)
292 REFCNT = 1
293 FLAGS = ()
294 IV = 0
295 NV = 0
296 ARRAY = 0xb2048
297 ALLOC = 0xb2048
298 FILL = 0
299 MAX = 0
300 ARYLEN = 0x0
301 FLAGS = (REAL)
302 Elt No. 0 0xb5658
303 SV = IV(0xbe860)
304 REFCNT = 1
305 FLAGS = (IOK,pIOK)
306 IV = 42
307 Elt No. 1 0xb5680
308 SV = IV(0xbe818)
309 REFCNT = 1
310 FLAGS = (IOK,pIOK)
311 IV = 24
312 Note that "Dump" will not report all the elements in the array, only
314 several first (depending on how deep it already went into the report
315 tree).
316 A reference to a hash
318 The following shows the raw form of a reference to a hash.
320 use Devel::Peek;
322 $a = {hello=>42};
323 Dump $a;
324 The output:
326 SV = RV(0x8177858) at 0x816a618
328 REFCNT = 1
329 FLAGS = (ROK)
330 RV = 0x814fc10
331 SV = PVHV(0x8167768) at 0x814fc10
332 REFCNT = 1
333 FLAGS = (SHAREKEYS)
334 IV = 1
335 NV = 0
336 ARRAY = 0x816c5b8 (0:7, 1:1)
337 hash quality = 100.0%
338 KEYS = 1
339 FILL = 1
340 MAX = 7
341 RITER = -1
342 EITER = 0x0
343 Elt "hello" HASH = 0xc8fd181b
344 SV = IV(0x816c030) at 0x814fcf4
345 REFCNT = 1
346 FLAGS = (IOK,pIOK)
347 IV = 42
348 This shows $a is a reference pointing to an SV. That SV is a PVHV, a
350 hash. Fields RITER and EITER are used by "each".
351 The "quality" of a hash is defined as the total number of comparisons
353 needed to access every element once, relative to the expected number
354 needed for a random hash. The value can go over 100%.
355 The total number of comparisons is equal to the sum of the squares of
357 the number of entries in each bucket. For a random hash of "<n"> keys
358 into "<k"> buckets, the expected value is:
359 n + n(n-1)/2k
361 Dumping a large array or hash
363 The "Dump()" function, by default, dumps up to 4 elements from a
365 toplevel array or hash. This number can be increased by supplying a
366 second argument to the function.
367 use Devel::Peek;
369 $a = [10,11,12,13,14];
370 Dump $a;
371 Notice that "Dump()" prints only elements 10 through 13 in the above
373 code. The following code will print all of the elements.
374 use Devel::Peek 'Dump';
376 $a = [10,11,12,13,14];
377 Dump $a, 5;
378 A reference to an SV which holds a C pointer
380 This is what you really need to know as an XS programmer, of course.
382 When an XSUB returns a pointer to a C structure that pointer is stored
383 in an SV and a reference to that SV is placed on the XSUB stack. So
384 the output from an XSUB which uses something like the T_PTROBJ map
385 might look something like this:
386 SV = RV(0xf381c)
388 REFCNT = 1
389 FLAGS = (ROK)
390 RV = 0xb8ad8
391 SV = PVMG(0xbb3c8)
392 REFCNT = 1
393 FLAGS = (OBJECT,IOK,pIOK)
394 IV = 729160
395 NV = 0
396 PV = 0
397 STASH = 0xc1d10 "CookBookB::Opaque"
398 This shows that we have an SV which is an RV. That RV points at
400 another SV. In this case that second SV is a PVMG, a blessed scalar.
401 Because it is blessed it has the "OBJECT" flag set. Note that an SV
402 which holds a C pointer also has the "IOK" flag set. The "STASH" is
403 set to the package name which this SV was blessed into.
404 The output from an XSUB which uses something like the T_PTRREF map,
406 which doesn't bless the object, might look something like this:
407 SV = RV(0xf381c)
409 REFCNT = 1
410 FLAGS = (ROK)
411 RV = 0xb8ad8
412 SV = PVMG(0xbb3c8)
413 REFCNT = 1
414 FLAGS = (IOK,pIOK)
415 IV = 729160
416 NV = 0
417 PV = 0
418 A reference to a subroutine
420 Looks like this:
422 SV = RV(0x798ec)
424 REFCNT = 1
425 FLAGS = (TEMP,ROK)
426 RV = 0x1d453c
427 SV = PVCV(0x1c768c)
428 REFCNT = 2
429 FLAGS = ()
430 IV = 0
431 NV = 0
432 COMP_STASH = 0x31068 "main"
433 START = 0xb20e0
434 ROOT = 0xbece0
435 XSUB = 0x0
436 XSUBANY = 0
437 GVGV::GV = 0x1d44e8 "MY" :: "top_targets"
438 FILE = "(eval 5)"
439 DEPTH = 0
440 PADLIST = 0x1c9338
441 This shows that
443 · the subroutine is not an XSUB (since "START" and "ROOT" are
445 non-zero, and "XSUB" is zero);
446 · that it was compiled in the package "main";
448 · under the name "MY::top_targets";
450 · inside a 5th eval in the program;
452 · it is not currently executed (see "DEPTH");
454 · it has no prototype ("PROTOTYPE" field is missing).
456
458 "Dump", "mstat", "DeadCode", "DumpArray", "DumpWithOP" and "DumpProg",
459 "fill_mstats", "mstats_fillhash", "mstats2hash" by default. Addition‐
460 ally available "SvREFCNT", "SvREFCNT_inc" and "SvREFCNT_dec".
461
463 Readers have been known to skip important parts of perlguts, causing
464 much frustration for all.
465
467 Ilya Zakharevich ilya@math.ohio-state.edu
468 Copyright (c) 1995-98 Ilya Zakharevich. All rights reserved. This pro‐
470 gram is free software; you can redistribute it and/or modify it under
471 the same terms as Perl itself.
472 Author of this software makes no claim whatsoever about suitability,
474 reliability, edability, editability or usability of this product, and
475 should not be kept liable for any damage resulting from the use of it.
476 If you can use it, you are in luck, if not, I should not be kept
477 responsible. Keep a handy copy of your backup tape at hand.
478
480 perlguts, and perlguts, again.
481perl v5.8.8 2001-09-21 Devel::Peek(3pm)