1Devel::Peek(3pm)       Perl Programmers Reference Guide       Devel::Peek(3pm)
2
3
4

NAME

6       Devel::Peek - A data debugging tool for the XS programmer
7

SYNOPSIS

9               use Devel::Peek;
10               Dump( $a );
11               Dump( $a, 5 );
12               DumpArray( 5, $a, $b, ... );
13               mstat "Point 5";
14
15               use Devel::Peek ':opd=st';
16

DESCRIPTION

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
25       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
29       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
39       Function "DumpArray()" allows dumping of multiple values (useful when
40       you need to analyze returns of functions).
41
42       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
46       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
51   Runtime debugging
52       "CvGV($cv)" return one of the globs associated to a subroutine
53       reference $cv.
54
55       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
62       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
68   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
73       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
77       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
81         minbucket nbuckets sbrk_good sbrk_slack sbrked_remains sbrks start_slack
82         topbucket topbucket_ev topbucket_odd total total_chain total_sbrk totfree
83
84       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
91       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
95       The information in
96
97        mem_size available_size minbucket nbuckets
98
99       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
104       "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
109       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
113       So, if you want to collect memory info in a cycle, you may call
114
115         $#buf = 999;
116         fill_mstats($_) for @buf;
117         mstats_fillhash(%report, 1);          # Static info too
118
119         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

EXAMPLES

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
138       Oh, one final bit of advice: take perlguts with you.  When you return
139       we expect to see it well-thumbed.
140
141   A simple scalar string
142       Let's begin by looking a simple scalar which is holding a string.
143
144               use Devel::Peek;
145               $a = "hello";
146               Dump $a;
147
148       The output:
149
150               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
158       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
168   A simple scalar number
169       If the scalar contains a number the raw SV will be leaner.
170
171               use Devel::Peek;
172               $a = 42;
173               Dump $a;
174
175       The output:
176
177               SV = IV(0xbc818)
178                 REFCNT = 1
179                 FLAGS = (IOK,pIOK)
180                 IV = 42
181
182       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
187   A simple scalar with an extra reference
188       If the scalar from the previous example had an extra reference:
189
190               use Devel::Peek;
191               $a = 42;
192               $b = \$a;
193               Dump $a;
194
195       The output:
196
197               SV = IV(0xbe860)
198                 REFCNT = 2
199                 FLAGS = (IOK,pIOK)
200                 IV = 42
201
202       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
206   A reference to a simple scalar
207       This shows what a reference looks like when it references a simple
208       scalar.
209
210               use Devel::Peek;
211               $a = 42;
212               $b = \$a;
213               Dump $b;
214
215       The output:
216
217               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
226       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
232       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
237   A reference to an array
238       This shows what a reference to an array looks like.
239
240               use Devel::Peek;
241               $a = [42];
242               Dump $a;
243
244       The output:
245
246               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
267       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
272       If $a pointed to an array of two elements then we would see the
273       following.
274
275               use Devel::Peek 'Dump';
276               $a = [42,24];
277               Dump $a;
278
279       The output:
280
281               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
307       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
311   A reference to a hash
312       The following shows the raw form of a reference to a hash.
313
314               use Devel::Peek;
315               $a = {hello=>42};
316               Dump $a;
317
318       The output:
319
320               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
342       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
345       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
349       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
353                       n + n(n-1)/2k
354
355   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
360               use Devel::Peek;
361               $a = [10,11,12,13,14];
362               Dump $a;
363
364       Notice that "Dump()" prints only elements 10 through 13 in the above
365       code.  The following code will print all of the elements.
366
367               use Devel::Peek 'Dump';
368               $a = [10,11,12,13,14];
369               Dump $a, 5;
370
371   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
378               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
390       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
396       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
399               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
410   A reference to a subroutine
411       Looks like this:
412
413               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
432       This shows that
433
434       ·   the subroutine is not an XSUB (since "START" and "ROOT" are non-
435           zero, and "XSUB" is zero);
436
437       ·   that it was compiled in the package "main";
438
439       ·   under the name "MY::top_targets";
440
441       ·   inside a 5th eval in the program;
442
443       ·   it is not currently executed (see "DEPTH");
444
445       ·   it has no prototype ("PROTOTYPE" field is missing).
446

EXPORTS

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

BUGS

453       Readers have been known to skip important parts of perlguts, causing
454       much frustration for all.
455

AUTHOR

457       Ilya Zakharevich    ilya@math.ohio-state.edu
458
459       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
463       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

SEE ALSO

470       perlguts, and perlguts, again.
471
472
473
474perl v5.12.4                      2011-06-07                  Devel::Peek(3pm)
Impressum