blib/lib/Test2/Tools/Refcount.pm

filter: Statementstmt 100% 47 / 47 Branchbran 100% 4 / 4 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 10 / 10 Podpod 100% 3 / 3 totaltotal 100% 64 / 64 CC 3 SCAR 4.1
CC
3
Cov
100%
is_refcount
3.0
BEGIN
1.0
BEGIN
1.0
CRAP 1.5
« blib/lib/Test2/Compare/Negatable.pm ↑ Summary blib/lib/Test2/Event/Pass.pm »
1 # You may distribute under the terms of either the GNU General Public License
2 # or the Artistic License (the same terms as Perl itself)
3 #
4 # (C) Paul Evans, 2008-2023 -- leonerd@leonerd.org.uk
5  
6 package Test2::Tools::Refcount;
7  
8 166 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
9 166 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 166 ▶use Test2::API qw(context release);
Subroutine BEGIN: called CC=1 SCAR=0.0
12  
13 166 ▶use Scalar::Util qw( weaken refaddr );
Subroutine BEGIN: called CC=1 SCAR=0.0
14 166 ▶use B qw( svref_2object );
Subroutine BEGIN: called CC=1 SCAR=0.0
15  
16 166 our $VERSION = '1.302226';
17  
18 166 our @EXPORT = qw(
19 is_refcount
20 is_oneref
21 );
22  
23 166 our @EXPORT_OK = qw(
24 refcount
25 );
26  
27 166 ▶use base qw(Exporter);
Subroutine BEGIN: called CC=1 SCAR=0.0
28  
29 166 ▶use constant HAVE_DEVEL_MAT_DUMPER => defined eval {
Subroutine BEGIN: called CC=1 SCAR=0.0
30 package # No Index
31 Devel::MAT::Dumper;
32 166 our $HELPER_PER_PACKAGE;
33 166 our $HELPER_PER_MAGIC;
34 166 require Devel::MAT::Dumper;
35 166 };
36  
37 =encoding UTF-8
38  
39 =head1 NAME
40  
41 C<Test2::Tools::Refcount> - assert reference counts on objects
42  
43 =head1 SYNOPSIS
44  
45 use Test2::Tools::Refcount;
46  
47 use Some::Class;
48 my $object = Some::Class->new();
49  
50 is_oneref( $object, '$object has a refcount of 1' );
51  
52 my $otherref = $object;
53  
54 is_refcount( $object, 2, '$object now has 2 references' );
55  
56 =head1 DESCRIPTION
57  
58 The Perl garbage collector uses simple reference counting during the normal
59 execution of a program. This means that cycles or unweakened references in
60 other parts of code can keep an object around for longer than intended. To
61 help avoid this problem, the reference count of a new object from its class
62 constructor ought to be 1. This way, the caller can know the object will be
63 properly DESTROYed when it drops all of its references to it.
64  
65 This module provides two test functions to help ensure this property holds
66 for an object class, so as to be polite to its callers.
67  
68 If the assertion fails; that is, if the actual reference count is different to
69 what was expected, either of the following two modules may be used to assist
70 the developer in finding where the references are.
71  
72 =over 4
73  
74 =item *
75  
76 If L<Devel::MAT> is installed, this test module will use it to dump the state
77 of the memory after a failure. It will create a F<.pmat> file named the same
78 as the unit test, but with the trailing F<.t> suffix replaced with
79 F<-TEST.pmat> where C<TEST> is the number of the test that failed (in case
80 there was more than one).
81  
82 =back
83  
84 See the examples below for more information.
85  
86 =cut
87  
88 =head1 FUNCTIONS
89  
90 =cut
91  
92 =head2 is_refcount
93  
94 is_refcount( $object, $count, $name )
95  
96 Test that $object has $count references to it.
97  
98 =cut
99  
100 sub is_refcount($$;$)
101 18 ▶{
Subroutine is_refcount: called CC=3 SCAR=11.0
Pod documented
102 18 my ( $object, $count, $name ) = @_;
103 18 @_ = ();
104  
105 18 my $ctx = context();
106  
107 18 ▶ if( !ref $object ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (ref $object) 1 17 18
108 1 my $ok = $ctx->ok( 0, $name );
109 1 $ctx->diag( " expected a reference, was not given one" );
110 1 $ctx->release;
111 1 return $ok;
112 }
113  
114 17 weaken $object; # So this reference itself doesn't show up
115  
116 17 my $REFCNT = refcount( $object );
117  
118 17 my $ok = $ctx->ok( $REFCNT == $count, $name );
119  
120 17 ▶ unless( $ok->pass ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($ok->pass) 3 14 17
121 3 $ctx->diag( " expected $count references, found $REFCNT" );
122  
123 3 if( HAVE_DEVEL_MAT_DUMPER ) {
124 my $file = $0;
125 my $hub = $ctx->hub;
126 my $num = $hub->count;
127  
128 # Trim the .t off first then append -$num.pmat, in case $0 wasn't a .t file
129 $file =~ s/\.(?:t|pm|pl)$//;
130 $file .= "-$num\.pmat";
131 $ctx->diag( sprintf "SV address is 0x%x", refaddr $object );
132 $ctx->diag( "Writing heap dump to $file" );
133 Devel::MAT::Dumper::dump( $file );
134 }
135 }
136  
137 17 $ctx->release;
138 17 return $ok;
139 }
140  
141 =head2 is_oneref
142  
143 is_oneref( $object, $name )
144  
145 Assert that the $object has only 1 reference to it.
146  
147 =cut
148  
149 sub is_oneref($;$)
150 5 ▶{
Subroutine is_oneref: called CC=1 SCAR=0.0
Pod documented
151 5 splice( @_, 1, 0, ( 1 ) );
152 5 goto &is_refcount;
153 }
154  
155 =head2 refcount
156  
157 $count = refcount( $object )
158  
159 Returns the reference count of the given object as used by the test functions.
160 This is useful for making tests that don't care what the count is before they
161 start, but simply assert that the count hasn't changed by the end.
162  
163 use Test2::Tools::Refcount import => [qw( is_refcount refcount )];
164 {
165 my $count = refcount( $object );
166  
167 do_something( $object );
168  
169 is_refcount( $object, $count, 'do_something() preserves refcount' );
170 }
171  
172 =cut
173  
174 sub refcount
175 17 ▶{
Subroutine refcount: called CC=1 SCAR=0.0
Pod documented
176 17 return svref_2object( $_[0] )->REFCNT;
177 }
178  
179 =head1 EXAMPLE
180  
181 Suppose, having written a new class C<MyBall>, you now want to check that its
182 constructor and methods are well-behaved, and don't leak references. Consider
183 the following test script:
184  
185 use Test::More tests => 2;
186 use Test2::Tools::Refcount;
187  
188 use MyBall;
189  
190 my $ball = MyBall->new();
191 is_oneref( $ball, 'One reference after construct' );
192  
193 $ball->bounce;
194  
195 # Any other code here that might be part of the test script
196  
197 is_oneref( $ball, 'One reference just before EOF' );
198  
199 The first assertion is just after the constructor, to check that the reference
200 returned by it is the only reference to that object. This fact is important if
201 we ever want C<DESTROY> to behave properly. The second call is right at the
202 end of the file, just before the main scope closes. At this stage we expect
203 the reference count also to be one, so that the object is properly cleaned up.
204  
205 Suppose, when run, this produces the following output (presuming
206 L<Devel::MAT::Dumper> is available):
207  
208 1..2
209 ok 1 - One reference after construct
210 not ok 2 - One reference just before EOF
211 # Failed test 'One reference just before EOF'
212 # at ex.pl line 26.
213 # expected 1 references, found 2
214 # SV address is 0x55e14c310278
215 # Writing heap dump to ex-2.pmat
216 # Looks like you failed 1 test of 2.
217  
218 This has written a F<ex-2.pmat> file we can load using the C<pmat> shell and
219 use the C<identify> command on the given address to find where it went:
220  
221 $ pmat ex-2.pmat
222 Perl memory dumpfile from perl 5.28.1 threaded
223 Heap contains 25233 objects
224 pmat> identify 0x55e14c310278
225 HASH(0)=MyBall at 0x55e14c310278 is:
226 ├─(via RV) the lexical $ball at depth 1 of CODE() at 0x55e14c3104a0=main_cv, which is:
227 │ └─the main code
228 └─(via RV) value {self} of HASH(2) at 0x55e14cacb860, which is (*A):
229 └─(via RV) value {cycle} of HASH(2) at 0x55e14cacb860, which is:
230 itself
231  
232 (This document isn't intended to be a full tutorial on L<Devel::MAT> and the
233 C<pmat> shell; for that see L<Devel::MAT::UserGuide>).
234  
235 From this output, we can see that the constructor was well-behaved, but that a
236 reference was leaked by the end of the script - the reference count was 2,
237 when we expected just 1. Reading the trace output, we can see that there were
238 2 references that could be found - one stored in the $ball lexical in the main
239 program, and one stored in a HASH. Since we expected to find the $ball lexical
240 variable, we know we are now looking for a leak in a hash somewhere in the
241 code. From reading the test script, we can guess this leak is likely to be in
242 the bounce() method. Furthermore, we know that the reference to the object
243 will be stored in a HASH in a member called C<self>.
244  
245 By reading the code which implements the bounce() method, we can see this is
246 indeed the case:
247  
248 sub bounce
249 {
250 my $self = shift;
251 my $cycle = { self => $self };
252 $cycle->{cycle} = $cycle;
253 }
254  
255 From reading the tracing output, we find that the HASH this object is
256 referenced in also contains a reference to itself, in a member called
257 C<cycle>. This comes from the last line in this function, a line that
258 purposely created a cycle, to demonstrate the point. While a real program
259 probably wouldn't do anything quite this obvious, the trace would still be
260 useful in finding the likely cause of the leak.
261  
262 If C<Devel::MAT::Dumper> is not available, then these detailed traces will not
263 be produced. The basic reference count testing will still take place, but a
264 smaller message will be produced:
265  
266 1..2
267 ok 1 - One reference after construct
268 not ok 2 - One reference just before EOF
269 # Failed test 'One reference just before EOF'
270 # at demo.pl line 16.
271 # expected 1 references, found 2
272 # Looks like you failed 1 test of 2.
273  
274 =head1 BUGS
275  
276 =over 4
277  
278 =item * Temporaries created on the stack
279  
280 Code which creates temporaries on the stack, to be released again when the
281 called function returns does not work correctly on perl 5.8 (and probably
282 before). Examples such as
283  
284 is_oneref( [] );
285  
286 may fail and claim a reference count of 2 instead.
287  
288 Passing a variable such as
289  
290 my $array = [];
291 is_oneref( $array );
292  
293 works fine. Because of the intention of this test module; that is, to assert
294 reference counts on some object stored in a variable during the lifetime of
295 the test script, this is unlikely to cause any problems.
296  
297 =back
298  
299 =head1 ACKNOWLEDGEMENTS
300  
301 Peter Rabbitson <ribasushi@cpan.org> - for suggesting using core's C<B>
302 instead of C<Devel::Refcount> to obtain refcounts
303  
304 =head1 AUTHOR
305  
306 Paul Evans <leonerd@leonerd.org.uk>
307  
308 =cut
309  
310 166 0x55AA;
« blib/lib/Test2/Compare/Negatable.pm ↑ Summary blib/lib/Test2/Event/Pass.pm »