This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Refactoring to Sv*_set() macros - patch #5
[perl5.git] / ext / Devel / Peek / Peek.pm
CommitLineData
3967c732
JD
1# Devel::Peek - A data debugging tool for the XS programmer
2# The documentation is after the __END__
3
4package Devel::Peek;
5
b162af07 6$VERSION = '1.03';
105cd853
YST
7$XS_VERSION = $VERSION;
8$VERSION = eval $VERSION;
3967c732
JD
9
10require Exporter;
9426adcd 11use XSLoader ();
3967c732 12
9426adcd 13@ISA = qw(Exporter);
d1424c31 14@EXPORT = qw(Dump mstat DeadCode DumpArray DumpWithOP DumpProg
bd16a5f0 15 fill_mstats mstats_fillhash mstats2hash runops_debug debug_flags);
83ee9e09 16@EXPORT_OK = qw(SvREFCNT SvREFCNT_inc SvREFCNT_dec CvGV);
3967c732
JD
17%EXPORT_TAGS = ('ALL' => [@EXPORT, @EXPORT_OK]);
18
9426adcd 19XSLoader::load 'Devel::Peek';
3967c732 20
1045810a
IZ
21sub import {
22 my $c = shift;
23 my $ops_rx = qr/^:opd(=[stP]*)?\b/;
24 my @db = grep m/$ops_rx/, @_;
25 @_ = grep !m/$ops_rx/, @_;
26 if (@db) {
27 die "Too many :opd options" if @db > 1;
28 runops_debug(1);
29 my $flags = ($db[0] =~ m/$ops_rx/ and $1);
30 $flags = 'st' unless defined $flags;
31 my $f = 0;
32 $f |= 2 if $flags =~ /s/;
33 $f |= 8 if $flags =~ /t/;
34 $f |= 64 if $flags =~ /P/;
35 $^D |= $f if $f;
36 }
37 unshift @_, $c;
38 goto &Exporter::import;
39}
40
3967c732
JD
41sub DumpWithOP ($;$) {
42 local($Devel::Peek::dump_ops)=1;
43 my $depth = @_ > 1 ? $_[1] : 4 ;
44 Dump($_[0],$depth);
45}
46
bd16a5f0
IZ
47$D_flags = 'psltocPmfrxuLHXDSTR';
48
49sub debug_flags (;$) {
50 my $out = "";
51 for my $i (0 .. length($D_flags)-1) {
52 $out .= substr $D_flags, $i, 1 if $^D & (1<<$i);
53 }
54 my $arg = shift;
55 my $num = $arg;
56 if (defined $arg and $arg =~ /\D/) {
57 die "unknown flags in debug_flags()" if $arg =~ /[^-$D_flags]/;
58 my ($on,$off) = split /-/, "$arg-";
59 $num = $^D;
60 $num |= (1<<index($D_flags, $_)) for split //, $on;
61 $num &= ~(1<<index($D_flags, $_)) for split //, $off;
62 }
63 $^D = $num if defined $arg;
64 $out
65}
66
3967c732
JD
671;
68__END__
69
70=head1 NAME
71
72Devel::Peek - A data debugging tool for the XS programmer
73
74=head1 SYNOPSIS
75
76 use Devel::Peek;
77 Dump( $a );
78 Dump( $a, 5 );
79 DumpArray( 5, $a, $b, ... );
80 mstat "Point 5";
81
1045810a
IZ
82 use Devel::Peek ':opd=st';
83
3967c732
JD
84=head1 DESCRIPTION
85
86Devel::Peek contains functions which allows raw Perl datatypes to be
87manipulated from a Perl script. This is used by those who do XS programming
88to check that the data they are sending from C to Perl looks as they think
89it should look. The trick, then, is to know what the raw datatype is
90supposed to look like when it gets to Perl. This document offers some tips
91and hints to describe good and bad raw data.
92
93It is very possible that this document will fall far short of being useful
94to the casual reader. The reader is expected to understand the material in
95the first few sections of L<perlguts>.
96
97Devel::Peek supplies a C<Dump()> function which can dump a raw Perl
98datatype, and C<mstat("marker")> function to report on memory usage
99(if perl is compiled with corresponding option). The function
100DeadCode() provides statistics on the data "frozen" into inactive
101C<CV>. Devel::Peek also supplies C<SvREFCNT()>, C<SvREFCNT_inc()>, and
102C<SvREFCNT_dec()> which can query, increment, and decrement reference
103counts on SVs. This document will take a passive, and safe, approach
104to data debugging and for that it will describe only the C<Dump()>
d1424c31 105function.
3967c732
JD
106
107Function C<DumpArray()> allows dumping of multiple values (useful when you
076c2fc0 108need to analyze returns of functions).
3967c732
JD
109
110The global variable $Devel::Peek::pv_limit can be set to limit the
111number of character printed in various string values. Setting it to 0
112means no limit.
113
1045810a
IZ
114If C<use Devel::Peek> directive has a C<:opd=FLAGS> argument,
115this switches on debugging of opcode dispatch. C<FLAGS> should be a
116combination of C<s>, C<t>, and C<P> (see B<-D> flags in L<perlrun>).
117C<:opd> is a shortcut for C<:opd=st>.
118
bd16a5f0
IZ
119=head2 Runtime debugging
120
121C<CvGV($cv)> return one of the globs associated to a subroutine reference $cv.
122
123debug_flags() returns a string representation of C<$^D> (similar to
124what is allowed for B<-D> flag). When called with a numeric argument,
125sets $^D to the corresponding value. When called with an argument of
126the form C<"flags-flags">, set on/off bits of C<$^D> corresponding to
127letters before/after C<->. (The returned value is for C<$^D> before
128the modification.)
129
130runops_debug() returns true if the current I<opcode dispatcher> is the
131debugging one. When called with an argument, switches to debugging or
132non-debugging dispatcher depending on the argument (active for
133newly-entered subs/etc only). (The returned value is for the dispatcher before the modification.)
134
d1424c31
IZ
135=head2 Memory footprint debugging
136
137When perl is compiled with support for memory footprint debugging
138(default with Perl's malloc()), Devel::Peek provides an access to this API.
139
140Use mstat() function to emit a memory state statistic to the terminal.
141For more information on the format of output of mstat() see
f3487f28 142L<perldebguts/Using C<$ENV{PERL_DEBUG_MSTATS}>>.
d1424c31
IZ
143
144Three additional functions allow access to this statistic from Perl.
145First, use C<mstats_fillhash(%hash)> to get the information contained
146in the output of mstat() into %hash. The field of this hash are
147
148 minbucket nbuckets sbrk_good sbrk_slack sbrked_remains sbrks start_slack
149 topbucket topbucket_ev topbucket_odd total total_chain total_sbrk totfree
150
151Two additional fields C<free>, C<used> contain array references which
152provide per-bucket count of free and used chunks. Two other fields
153C<mem_size>, C<available_size> contain array references which provide
154the information about the allocated size and usable size of chunks in
f3487f28 155each bucket. Again, see L<perldebguts/Using C<$ENV{PERL_DEBUG_MSTATS}>>
d1424c31
IZ
156for details.
157
158Keep in mind that only the first several "odd-numbered" buckets are
159used, so the information on size of the "odd-numbered" buckets which are
160not used is probably meaningless.
161
162The information in
163
164 mem_size available_size minbucket nbuckets
165
166is the property of a particular build of perl, and does not depend on
167the current process. If you do not provide the optional argument to
168the functions mstats_fillhash(), fill_mstats(), mstats2hash(), then
169the information in fields C<mem_size>, C<available_size> is not
170updated.
171
172C<fill_mstats($buf)> is a much cheaper call (both speedwise and
173memory-wise) which collects the statistic into $buf in
174machine-readable form. At a later moment you may need to call
175C<mstats2hash($buf, %hash)> to use this information to fill %hash.
176
177All three APIs C<fill_mstats($buf)>, C<mstats_fillhash(%hash)>, and
178C<mstats2hash($buf, %hash)> are designed to allocate no memory if used
179I<the second time> on the same $buf and/or %hash.
180
181So, if you want to collect memory info in a cycle, you may call
182
183 $#buf = 999;
184 fill_mstats($_) for @buf;
185 mstats_fillhash(%report, 1); # Static info too
186
187 foreach (@buf) {
188 # Do something...
189 fill_mstats $_; # Collect statistic
190 }
191 foreach (@buf) {
192 mstats2hash($_, %report); # Preserve static info
193 # Do something with %report
194 }
195
3967c732
JD
196=head1 EXAMPLES
197
198The following examples don't attempt to show everything as that would be a
199monumental task, and, frankly, we don't want this manpage to be an internals
200document for Perl. The examples do demonstrate some basics of the raw Perl
201datatypes, and should suffice to get most determined people on their way.
202There are no guidewires or safety nets, nor blazed trails, so be prepared to
203travel alone from this point and on and, if at all possible, don't fall into
204the quicksand (it's bad for business).
205
206Oh, one final bit of advice: take L<perlguts> with you. When you return we
207expect to see it well-thumbed.
208
209=head2 A simple scalar string
210
211Let's begin by looking a simple scalar which is holding a string.
212
a423dfdd 213 use Devel::Peek;
3967c732
JD
214 $a = "hello";
215 Dump $a;
216
217The output:
218
219 SV = PVIV(0xbc288)
220 REFCNT = 1
221 FLAGS = (POK,pPOK)
222 IV = 0
223 PV = 0xb2048 "hello"\0
224 CUR = 5
225 LEN = 6
226
227This says C<$a> is an SV, a scalar. The scalar is a PVIV, a string.
228Its reference count is 1. It has the C<POK> flag set, meaning its
229current PV field is valid. Because POK is set we look at the PV item
230to see what is in the scalar. The \0 at the end indicate that this
231PV is properly NUL-terminated.
232If the FLAGS had been IOK we would look
233at the IV item. CUR indicates the number of characters in the PV.
234LEN indicates the number of bytes requested for the PV (one more than
235CUR, in this case, because LEN includes an extra byte for the
236end-of-string marker).
237
238=head2 A simple scalar number
239
240If the scalar contains a number the raw SV will be leaner.
241
a423dfdd 242 use Devel::Peek;
3967c732
JD
243 $a = 42;
244 Dump $a;
245
246The output:
247
248 SV = IV(0xbc818)
249 REFCNT = 1
250 FLAGS = (IOK,pIOK)
251 IV = 42
252
253This says C<$a> is an SV, a scalar. The scalar is an IV, a number. Its
254reference count is 1. It has the C<IOK> flag set, meaning it is currently
255being evaluated as a number. Because IOK is set we look at the IV item to
256see what is in the scalar.
257
258=head2 A simple scalar with an extra reference
259
260If the scalar from the previous example had an extra reference:
261
a423dfdd 262 use Devel::Peek;
3967c732
JD
263 $a = 42;
264 $b = \$a;
265 Dump $a;
266
267The output:
268
269 SV = IV(0xbe860)
270 REFCNT = 2
271 FLAGS = (IOK,pIOK)
272 IV = 42
273
274Notice that this example differs from the previous example only in its
275reference count. Compare this to the next example, where we dump C<$b>
276instead of C<$a>.
277
278=head2 A reference to a simple scalar
279
280This shows what a reference looks like when it references a simple scalar.
281
a423dfdd 282 use Devel::Peek;
3967c732
JD
283 $a = 42;
284 $b = \$a;
285 Dump $b;
286
287The output:
288
289 SV = RV(0xf041c)
290 REFCNT = 1
291 FLAGS = (ROK)
292 RV = 0xbab08
293 SV = IV(0xbe860)
294 REFCNT = 2
295 FLAGS = (IOK,pIOK)
296 IV = 42
297
298Starting from the top, this says C<$b> is an SV. The scalar is an RV, a
299reference. It has the C<ROK> flag set, meaning it is a reference. Because
300ROK is set we have an RV item rather than an IV or PV. Notice that Dump
301follows the reference and shows us what C<$b> was referencing. We see the
302same C<$a> that we found in the previous example.
303
304Note that the value of C<RV> coincides with the numbers we see when we
305stringify $b. The addresses inside RV() and IV() are addresses of
306C<X***> structure which holds the current state of an C<SV>. This
307address may change during lifetime of an SV.
308
309=head2 A reference to an array
310
311This shows what a reference to an array looks like.
312
a423dfdd 313 use Devel::Peek;
3967c732
JD
314 $a = [42];
315 Dump $a;
316
317The output:
318
319 SV = RV(0xf041c)
320 REFCNT = 1
321 FLAGS = (ROK)
322 RV = 0xb2850
323 SV = PVAV(0xbd448)
324 REFCNT = 1
325 FLAGS = ()
326 IV = 0
327 NV = 0
328 ARRAY = 0xb2048
329 ALLOC = 0xb2048
330 FILL = 0
331 MAX = 0
332 ARYLEN = 0x0
333 FLAGS = (REAL)
334 Elt No. 0 0xb5658
335 SV = IV(0xbe860)
336 REFCNT = 1
337 FLAGS = (IOK,pIOK)
338 IV = 42
339
340This says C<$a> is an SV and that it is an RV. That RV points to
341another SV which is a PVAV, an array. The array has one element,
342element zero, which is another SV. The field C<FILL> above indicates
343the last element in the array, similar to C<$#$a>.
344
345If C<$a> pointed to an array of two elements then we would see the
346following.
347
348 use Devel::Peek 'Dump';
349 $a = [42,24];
350 Dump $a;
351
352The output:
353
354 SV = RV(0xf041c)
355 REFCNT = 1
356 FLAGS = (ROK)
357 RV = 0xb2850
358 SV = PVAV(0xbd448)
359 REFCNT = 1
360 FLAGS = ()
361 IV = 0
362 NV = 0
363 ARRAY = 0xb2048
364 ALLOC = 0xb2048
365 FILL = 0
366 MAX = 0
367 ARYLEN = 0x0
368 FLAGS = (REAL)
369 Elt No. 0 0xb5658
370 SV = IV(0xbe860)
371 REFCNT = 1
372 FLAGS = (IOK,pIOK)
373 IV = 42
374 Elt No. 1 0xb5680
375 SV = IV(0xbe818)
376 REFCNT = 1
377 FLAGS = (IOK,pIOK)
378 IV = 24
379
380Note that C<Dump> will not report I<all> the elements in the array,
381only several first (depending on how deep it already went into the
382report tree).
383
384=head2 A reference to a hash
385
386The following shows the raw form of a reference to a hash.
387
a423dfdd 388 use Devel::Peek;
3967c732
JD
389 $a = {hello=>42};
390 Dump $a;
391
392The output:
393
d5889220
T
394 SV = RV(0x8177858) at 0x816a618
395 REFCNT = 1
396 FLAGS = (ROK)
397 RV = 0x814fc10
398 SV = PVHV(0x8167768) at 0x814fc10
399 REFCNT = 1
400 FLAGS = (SHAREKEYS)
401 IV = 1
402 NV = 0
403 ARRAY = 0x816c5b8 (0:7, 1:1)
404 hash quality = 100.0%
405 KEYS = 1
406 FILL = 1
407 MAX = 7
408 RITER = -1
409 EITER = 0x0
410 Elt "hello" HASH = 0xc8fd181b
411 SV = IV(0x816c030) at 0x814fcf4
412 REFCNT = 1
413 FLAGS = (IOK,pIOK)
414 IV = 42
3967c732
JD
415
416This shows C<$a> is a reference pointing to an SV. That SV is a PVHV, a
417hash. Fields RITER and EITER are used by C<L<each>>.
418
d5889220
T
419The "quality" of a hash is defined as the total number of comparisons needed
420to access every element once, relative to the expected number needed for a
421random hash. The value can go over 100%.
422
423The total number of comparisons is equal to the sum of the squares of the
424number of entries in each bucket. For a random hash of C<<n>> keys into
425C<<k>> buckets, the expected value is:
426
427 n + n(n-1)/2k
428
3967c732
JD
429=head2 Dumping a large array or hash
430
431The C<Dump()> function, by default, dumps up to 4 elements from a
432toplevel array or hash. This number can be increased by supplying a
433second argument to the function.
434
a423dfdd 435 use Devel::Peek;
3967c732
JD
436 $a = [10,11,12,13,14];
437 Dump $a;
438
439Notice that C<Dump()> prints only elements 10 through 13 in the above code.
440The following code will print all of the elements.
441
442 use Devel::Peek 'Dump';
443 $a = [10,11,12,13,14];
444 Dump $a, 5;
445
446=head2 A reference to an SV which holds a C pointer
447
448This is what you really need to know as an XS programmer, of course. When
449an XSUB returns a pointer to a C structure that pointer is stored in an SV
450and a reference to that SV is placed on the XSUB stack. So the output from
451an XSUB which uses something like the T_PTROBJ map might look something like
452this:
453
454 SV = RV(0xf381c)
455 REFCNT = 1
456 FLAGS = (ROK)
457 RV = 0xb8ad8
458 SV = PVMG(0xbb3c8)
459 REFCNT = 1
460 FLAGS = (OBJECT,IOK,pIOK)
461 IV = 729160
462 NV = 0
463 PV = 0
464 STASH = 0xc1d10 "CookBookB::Opaque"
465
466This shows that we have an SV which is an RV. That RV points at another
467SV. In this case that second SV is a PVMG, a blessed scalar. Because it is
468blessed it has the C<OBJECT> flag set. Note that an SV which holds a C
469pointer also has the C<IOK> flag set. The C<STASH> is set to the package
470name which this SV was blessed into.
471
472The output from an XSUB which uses something like the T_PTRREF map, which
473doesn't bless the object, might look something like this:
474
475 SV = RV(0xf381c)
476 REFCNT = 1
477 FLAGS = (ROK)
478 RV = 0xb8ad8
479 SV = PVMG(0xbb3c8)
480 REFCNT = 1
481 FLAGS = (IOK,pIOK)
482 IV = 729160
483 NV = 0
484 PV = 0
485
486=head2 A reference to a subroutine
487
488Looks like this:
489
490 SV = RV(0x798ec)
491 REFCNT = 1
492 FLAGS = (TEMP,ROK)
493 RV = 0x1d453c
494 SV = PVCV(0x1c768c)
495 REFCNT = 2
496 FLAGS = ()
497 IV = 0
498 NV = 0
499 COMP_STASH = 0x31068 "main"
500 START = 0xb20e0
501 ROOT = 0xbece0
502 XSUB = 0x0
503 XSUBANY = 0
504 GVGV::GV = 0x1d44e8 "MY" :: "top_targets"
57843af0 505 FILE = "(eval 5)"
3967c732
JD
506 DEPTH = 0
507 PADLIST = 0x1c9338
508
509This shows that
510
bbc7dcd2 511=over 4
3967c732 512
a45bd81d 513=item *
3967c732
JD
514
515the subroutine is not an XSUB (since C<START> and C<ROOT> are
516non-zero, and C<XSUB> is zero);
517
a45bd81d 518=item *
3967c732
JD
519
520that it was compiled in the package C<main>;
521
a45bd81d 522=item *
3967c732
JD
523
524under the name C<MY::top_targets>;
525
a45bd81d 526=item *
3967c732
JD
527
528inside a 5th eval in the program;
529
a45bd81d 530=item *
3967c732
JD
531
532it is not currently executed (see C<DEPTH>);
533
a45bd81d 534=item *
3967c732
JD
535
536it has no prototype (C<PROTOTYPE> field is missing).
537
a45bd81d 538=back
3967c732
JD
539
540=head1 EXPORTS
541
542C<Dump>, C<mstat>, C<DeadCode>, C<DumpArray>, C<DumpWithOP> and
7c6ca602 543C<DumpProg>, C<fill_mstats>, C<mstats_fillhash>, C<mstats2hash> by
d1424c31
IZ
544default. Additionally available C<SvREFCNT>, C<SvREFCNT_inc> and
545C<SvREFCNT_dec>.
3967c732
JD
546
547=head1 BUGS
548
549Readers have been known to skip important parts of L<perlguts>, causing much
550frustration for all.
551
552=head1 AUTHOR
553
554Ilya Zakharevich ilya@math.ohio-state.edu
555
556Copyright (c) 1995-98 Ilya Zakharevich. All rights reserved.
557This program is free software; you can redistribute it and/or
558modify it under the same terms as Perl itself.
559
560Author of this software makes no claim whatsoever about suitability,
561reliability, edability, editability or usability of this product, and
562should not be kept liable for any damage resulting from the use of
563it. If you can use it, you are in luck, if not, I should not be kept
564responsible. Keep a handy copy of your backup tape at hand.
565
566=head1 SEE ALSO
567
568L<perlguts>, and L<perlguts>, again.
569
570=cut