1Test::MemoryGrowth(3) User Contributed Perl DocumentationTest::MemoryGrowth(3)
2
6 "Test::MemoryGrowth" - assert that code does not cause growth in memory
7 usage
8
10 use Test::More tests => 3;
11 use Test::MemoryGrowth;
12 use Some::Class;
14 no_growth {
16 my $obj = Some::Class->new;
17 } 'Constructing Some::Class does not grow memory';
18 my $obj = Some::Class->new;
20 no_growth {
21 $obj->do_thing;
22 } 'Some::Class->do_thing does not grow memory';
23 #### This test will fail ####
26 my @list;
27 no_growth {
28 push @list, "Hello world";
29 } 'pushing to an array does not grow memory';
30
32 This module provides a function to check that a given block of code
33 does not result in the process consuming extra memory once it has
34 finished. Despite the name of this module it does not, in the strictest
35 sense of the word, test for a memory leak: that term is specifically
36 applied to cases where memory has been allocated but all record of it
37 has been lost, so it cannot possibly be reclaimed. While the method
38 employed by this module can detect such bugs, it can also detect cases
39 where memory is still referenced and reachable, but the usage has grown
40 more than would be expected or necessary.
41 The block of code will be run a large number of times (by default
43 10,000), and the difference in memory usage by the process before and
44 after is compared. If the memory usage has now increased by more than
45 one byte per call, then the test fails.
46 In order to give the code a chance to load initial resources it needs,
48 it will be run a few times first (by default 10); giving it a chance to
49 load files, AUTOLOADs, caches, or any other information that it
50 requires. Any extra memory usage here will not count against it.
51 This simple method is not a guaranteed indicator of the absence of
53 memory resource bugs from a piece of code; it has the possibility to
54 fail in both a false-negative and a false-positive way.
55 False Negative
57 It is possible that a piece of code causes memory usage growth that
58 this module does not detect. Because it only detects memory growth
59 of at least one byte per call, it cannot detect cases of linear
60 memory growth at lower rates than this. Most memory usage growth
61 comes either from Perl-level or C-level bugs where memory objects
62 are created at every call and not reclaimed again. (These are
63 either genuine memory leaks, or needless allocations of objects
64 that are stored somewhere and never reclaimed). It is unlikely such
65 a bug would result in a growth rate smaller than one byte per call.
66 A second failure case comes from the fact that memory usage is
68 taken from the Operating System's measure of the process's Virtual
69 Memory size, so as to be able to detect memory usage growth in C
70 libraries or XS-level wrapping code, as well as Perl functions.
71 Because Perl does not agressively return unused memory to the
72 Operating System, it is possible that a piece of code could use un-
73 allocated but un-reclaimed memory to grow into; resulting in an
74 increase in its requirements despite not requesting extra memory
75 from the Operating System.
76 False Positive
78 It is possible that the test will claim that a function grows in
79 memory, when the behaviour is in fact perfectly normal for the code
80 in question. For example, the code could simply be some function
81 whose behaviour is required to store extra state; for example,
82 adding a new item into a list. In this case it is in fact expected
83 that the memory usage of the process will increase.
84 By careful use of this test module, false indications can be minimised.
86 By splitting tests across many test scripts, each one can be started in
87 a new process state, where most of the memory assigned from the
88 Operating System is in use by Perl, so anything extra that the code
89 requires will have to request more. This should reduce the false
90 negative indications.
91 By keeping in mind that the module simply measures the change in
93 allocated memory size, false positives can be minimised, by not
94 attempting to assert that certain pieces of code do not grow in memory,
95 when in fact it would be expected that they do.
96 Devel::MAT Integration
98 If Devel::MAT is installed, this test module will use it to dump the
99 state of the memory after a failure. It will create a .pmat file named
100 the same as the unit test, but with the trailing .t suffix replaced
101 with -TEST.pmat where "TEST" is the number of the test that failed (in
102 case there was more than one).
103
105 no_growth { CODE } %opts, $name
106 Assert that the code block does not consume extra memory.
107 Takes the following named arguments:
109 calls => INT
111 The number of times to call the code during growth testing.
112 burn_in => INT
114 The number of times to call the code initially, before watching
115 for memory usage.
116
118 ยท Don't be Linux Specific
119 Currently, this module uses a very Linux-specific method of
121 determining process memory usage (namely, by inspecting
122 /proc/self/status). This should really be fixed to some OS-
123 neutral abstraction. Currently I am unaware of a simple
124 portable mechanism to query this. Patches very much welcome. :)
125
127 Paul Evans <leonerd@leonerd.org.uk>
128perl v5.28.0 2018-07-15 Test::MemoryGrowth(3)