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
20 programming to check that the data they are sending from C to Perl
21 looks as they think it should look. The trick, then, is to know what
22 the raw datatype is supposed to look like when it gets to Perl. This
23 document 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
34 "SvREFCNT_dec()" which can query, increment, and decrement reference
35 counts on SVs. This document will take a passive, and safe, approach
36 to data debugging and for that it will describe only the "Dump()"
37 function.
38 Function "DumpArray()" allows dumping of multiple values (useful when
40 you need to analyze returns of functions).
41 The global variable $Devel::Peek::pv_limit can be set to limit the
43 number of character printed in various string values. Setting it to 0
44 means no limit.
45 If "use Devel::Peek" directive has a ":opd=FLAGS" argument, this
47 switches on debugging of opcode dispatch. "FLAGS" should be a
48 combination of "s", "t", and "P" (see -D flags in perlrun). ":opd" is
49 a shortcut for ":opd=st".
50 Runtime debugging
52 "CvGV($cv)" return one of the globs associated to a subroutine
53 reference $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
60 modification.)
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
70 (default with Perl's malloc()), Devel::Peek provides an access to this
71 API.
72 Use mstat() function to emit a memory state statistic to the terminal.
74 For more information on the format of output of mstat() see "Using
75 $ENV{PERL_DEBUG_MSTATS}" in perldebguts.
76 Three additional functions allow access to this statistic from Perl.
78 First, use "mstats_fillhash(%hash)" to get the information contained in
79 the output of mstat() into %hash. The field of this hash are
80 minbucket nbuckets sbrk_good sbrk_slack sbrked_remains sbrks start_slack
82 topbucket topbucket_ev topbucket_odd total total_chain total_sbrk totfree
83 Two additional fields "free", "used" contain array references which
85 provide per-bucket count of free and used chunks. Two other fields
86 "mem_size", "available_size" contain array references which provide the
87 information about the allocated size and usable size of chunks in each
88 bucket. Again, see "Using $ENV{PERL_DEBUG_MSTATS}" in perldebguts for
89 details.
90 Keep in mind that only the first several "odd-numbered" buckets are
92 used, so the information on size of the "odd-numbered" buckets which
93 are not used is probably meaningless.
94 The information in
96 mem_size available_size minbucket nbuckets
98 is the property of a particular build of perl, and does not depend on
100 the current process. If you do not provide the optional argument to
101 the functions mstats_fillhash(), fill_mstats(), mstats2hash(), then the
102 information in fields "mem_size", "available_size" is not updated.
103 "fill_mstats($buf)" is a much cheaper call (both speedwise and memory-
105 wise) which collects the statistic into $buf in machine-readable form.
106 At a later moment you may need to call "mstats2hash($buf, %hash)" to
107 use this information to fill %hash.
108 All three APIs "fill_mstats($buf)", "mstats_fillhash(%hash)", and
110 "mstats2hash($buf, %hash)" are designed to allocate no memory if used
111 the second time on the same $buf and/or %hash.
112 So, if you want to collect memory info in a cycle, you may call
114 $#buf = 999;
116 fill_mstats($_) for @buf;
117 mstats_fillhash(%report, 1); # Static info too
118 foreach (@buf) {
120 # Do something...
121 fill_mstats $_; # Collect statistic
122 }
123 foreach (@buf) {
124 mstats2hash($_, %report); # Preserve static info
125 # Do something with %report
126 }
127
129 The following examples don't attempt to show everything as that would
130 be a monumental task, and, frankly, we don't want this manpage to be an
131 internals document for Perl. The examples do demonstrate some basics
132 of the raw Perl datatypes, and should suffice to get most determined
133 people on their way. There are no guidewires or safety nets, nor
134 blazed trails, so be prepared to travel alone from this point and on
135 and, if at all possible, don't fall into the quicksand (it's bad for
136 business).
137 Oh, one final bit of advice: take perlguts with you. When you return
139 we expect to see it well-thumbed.
140 A simple scalar string
142 Let's begin by looking a simple scalar which is holding a string.
143 use Devel::Peek;
145 $a = "hello";
146 Dump $a;
147 The output:
149 SV = PVIV(0xbc288)
151 REFCNT = 1
152 FLAGS = (POK,pPOK)
153 IV = 0
154 PV = 0xb2048 "hello"\0
155 CUR = 5
156 LEN = 6
157 This says $a is an SV, a scalar. The scalar is a PVIV, a string. Its
159 reference count is 1. It has the "POK" flag set, meaning its current
160 PV field is valid. Because POK is set we look at the PV item to see
161 what is in the scalar. The \0 at the end indicate that this PV is
162 properly NUL-terminated. If the FLAGS had been IOK we would look at
163 the IV item. CUR indicates the number of characters in the PV. LEN
164 indicates the number of bytes requested for the PV (one more than CUR,
165 in this case, because LEN includes an extra byte for the end-of-string
166 marker).
167 A simple scalar number
169 If the scalar contains a number the raw SV will be leaner.
170 use Devel::Peek;
172 $a = 42;
173 Dump $a;
174 The output:
176 SV = IV(0xbc818)
178 REFCNT = 1
179 FLAGS = (IOK,pIOK)
180 IV = 42
181 This says $a is an SV, a scalar. The scalar is an IV, a number. Its
183 reference count is 1. It has the "IOK" flag set, meaning it is
184 currently being evaluated as a number. Because IOK is set we look at
185 the IV item to see what is in the scalar.
186 A simple scalar with an extra reference
188 If the scalar from the previous example had an extra reference:
189 use Devel::Peek;
191 $a = 42;
192 $b = \$a;
193 Dump $a;
194 The output:
196 SV = IV(0xbe860)
198 REFCNT = 2
199 FLAGS = (IOK,pIOK)
200 IV = 42
201 Notice that this example differs from the previous example only in its
203 reference count. Compare this to the next example, where we dump $b
204 instead of $a.
205 A reference to a simple scalar
207 This shows what a reference looks like when it references a simple
208 scalar.
209 use Devel::Peek;
211 $a = 42;
212 $b = \$a;
213 Dump $b;
214 The output:
216 SV = RV(0xf041c)
218 REFCNT = 1
219 FLAGS = (ROK)
220 RV = 0xbab08
221 SV = IV(0xbe860)
222 REFCNT = 2
223 FLAGS = (IOK,pIOK)
224 IV = 42
225 Starting from the top, this says $b is an SV. The scalar is an RV, a
227 reference. It has the "ROK" flag set, meaning it is a reference.
228 Because ROK is set we have an RV item rather than an IV or PV. Notice
229 that Dump follows the reference and shows us what $b was referencing.
230 We see the same $a that we found in the previous example.
231 Note that the value of "RV" coincides with the numbers we see when we
233 stringify $b. The addresses inside RV() and IV() are addresses of
234 "X***" structure which holds the current state of an "SV". This address
235 may change during lifetime of an SV.
236 A reference to an array
238 This shows what a reference to an array looks like.
239 use Devel::Peek;
241 $a = [42];
242 Dump $a;
243 The output:
245 SV = RV(0xf041c)
247 REFCNT = 1
248 FLAGS = (ROK)
249 RV = 0xb2850
250 SV = PVAV(0xbd448)
251 REFCNT = 1
252 FLAGS = ()
253 IV = 0
254 NV = 0
255 ARRAY = 0xb2048
256 ALLOC = 0xb2048
257 FILL = 0
258 MAX = 0
259 ARYLEN = 0x0
260 FLAGS = (REAL)
261 Elt No. 0 0xb5658
262 SV = IV(0xbe860)
263 REFCNT = 1
264 FLAGS = (IOK,pIOK)
265 IV = 42
266 This says $a is an SV and that it is an RV. That RV points to another
268 SV which is a PVAV, an array. The array has one element, element zero,
269 which is another SV. The field "FILL" above indicates the last element
270 in the array, similar to "$#$a".
271 If $a pointed to an array of two elements then we would see the
273 following.
274 use Devel::Peek 'Dump';
276 $a = [42,24];
277 Dump $a;
278 The output:
280 SV = RV(0xf041c)
282 REFCNT = 1
283 FLAGS = (ROK)
284 RV = 0xb2850
285 SV = PVAV(0xbd448)
286 REFCNT = 1
287 FLAGS = ()
288 IV = 0
289 NV = 0
290 ARRAY = 0xb2048
291 ALLOC = 0xb2048
292 FILL = 0
293 MAX = 0
294 ARYLEN = 0x0
295 FLAGS = (REAL)
296 Elt No. 0 0xb5658
297 SV = IV(0xbe860)
298 REFCNT = 1
299 FLAGS = (IOK,pIOK)
300 IV = 42
301 Elt No. 1 0xb5680
302 SV = IV(0xbe818)
303 REFCNT = 1
304 FLAGS = (IOK,pIOK)
305 IV = 24
306 Note that "Dump" will not report all the elements in the array, only
308 several first (depending on how deep it already went into the report
309 tree).
310 A reference to a hash
312 The following shows the raw form of a reference to a hash.
313 use Devel::Peek;
315 $a = {hello=>42};
316 Dump $a;
317 The output:
319 SV = RV(0x8177858) at 0x816a618
321 REFCNT = 1
322 FLAGS = (ROK)
323 RV = 0x814fc10
324 SV = PVHV(0x8167768) at 0x814fc10
325 REFCNT = 1
326 FLAGS = (SHAREKEYS)
327 IV = 1
328 NV = 0
329 ARRAY = 0x816c5b8 (0:7, 1:1)
330 hash quality = 100.0%
331 KEYS = 1
332 FILL = 1
333 MAX = 7
334 RITER = -1
335 EITER = 0x0
336 Elt "hello" HASH = 0xc8fd181b
337 SV = IV(0x816c030) at 0x814fcf4
338 REFCNT = 1
339 FLAGS = (IOK,pIOK)
340 IV = 42
341 This shows $a is a reference pointing to an SV. That SV is a PVHV, a
343 hash. Fields RITER and EITER are used by "each".
344 The "quality" of a hash is defined as the total number of comparisons
346 needed to access every element once, relative to the expected number
347 needed for a random hash. The value can go over 100%.
348 The total number of comparisons is equal to the sum of the squares of
350 the number of entries in each bucket. For a random hash of "<n"> keys
351 into "<k"> buckets, the expected value is:
352 n + n(n-1)/2k
354 Dumping a large array or hash
356 The "Dump()" function, by default, dumps up to 4 elements from a
357 toplevel array or hash. This number can be increased by supplying a
358 second argument to the function.
359 use Devel::Peek;
361 $a = [10,11,12,13,14];
362 Dump $a;
363 Notice that "Dump()" prints only elements 10 through 13 in the above
365 code. The following code will print all of the elements.
366 use Devel::Peek 'Dump';
368 $a = [10,11,12,13,14];
369 Dump $a, 5;
370 A reference to an SV which holds a C pointer
372 This is what you really need to know as an XS programmer, of course.
373 When an XSUB returns a pointer to a C structure that pointer is stored
374 in an SV and a reference to that SV is placed on the XSUB stack. So
375 the output from an XSUB which uses something like the T_PTROBJ map
376 might look something like this:
377 SV = RV(0xf381c)
379 REFCNT = 1
380 FLAGS = (ROK)
381 RV = 0xb8ad8
382 SV = PVMG(0xbb3c8)
383 REFCNT = 1
384 FLAGS = (OBJECT,IOK,pIOK)
385 IV = 729160
386 NV = 0
387 PV = 0
388 STASH = 0xc1d10 "CookBookB::Opaque"
389 This shows that we have an SV which is an RV. That RV points at
391 another SV. In this case that second SV is a PVMG, a blessed scalar.
392 Because it is blessed it has the "OBJECT" flag set. Note that an SV
393 which holds a C pointer also has the "IOK" flag set. The "STASH" is
394 set to the package name which this SV was blessed into.
395 The output from an XSUB which uses something like the T_PTRREF map,
397 which doesn't bless the object, might look something like this:
398 SV = RV(0xf381c)
400 REFCNT = 1
401 FLAGS = (ROK)
402 RV = 0xb8ad8
403 SV = PVMG(0xbb3c8)
404 REFCNT = 1
405 FLAGS = (IOK,pIOK)
406 IV = 729160
407 NV = 0
408 PV = 0
409 A reference to a subroutine
411 Looks like this:
412 SV = RV(0x798ec)
414 REFCNT = 1
415 FLAGS = (TEMP,ROK)
416 RV = 0x1d453c
417 SV = PVCV(0x1c768c)
418 REFCNT = 2
419 FLAGS = ()
420 IV = 0
421 NV = 0
422 COMP_STASH = 0x31068 "main"
423 START = 0xb20e0
424 ROOT = 0xbece0
425 XSUB = 0x0
426 XSUBANY = 0
427 GVGV::GV = 0x1d44e8 "MY" :: "top_targets"
428 FILE = "(eval 5)"
429 DEPTH = 0
430 PADLIST = 0x1c9338
431 This shows that
433 · the subroutine is not an XSUB (since "START" and "ROOT" are non-
435 zero, and "XSUB" is zero);
436 · that it was compiled in the package "main";
438 · under the name "MY::top_targets";
440 · inside a 5th eval in the program;
442 · it is not currently executed (see "DEPTH");
444 · it has no prototype ("PROTOTYPE" field is missing).
446
448 "Dump", "mstat", "DeadCode", "DumpArray", "DumpWithOP" and "DumpProg",
449 "fill_mstats", "mstats_fillhash", "mstats2hash" by default.
450 Additionally available "SvREFCNT", "SvREFCNT_inc" and "SvREFCNT_dec".
451
453 Readers have been known to skip important parts of perlguts, causing
454 much frustration for all.
455
457 Ilya Zakharevich ilya@math.ohio-state.edu
458 Copyright (c) 1995-98 Ilya Zakharevich. All rights reserved. This
460 program is free software; you can redistribute it and/or modify it
461 under the same terms as Perl itself.
462 Author of this software makes no claim whatsoever about suitability,
464 reliability, edability, editability or usability of this product, and
465 should not be kept liable for any damage resulting from the use of it.
466 If you can use it, you are in luck, if not, I should not be kept
467 responsible. Keep a handy copy of your backup tape at hand.
468
470 perlguts, and perlguts, again.
471perl v5.12.4 2011-06-07 Devel::Peek(3pm)