4 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS $warn);
9 @ISA = qw(Exporter DynaLoader);
11 # This allows declaration use Devel::Size ':all';
12 %EXPORT_TAGS = ( 'all' => [ qw(
16 @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
21 bootstrap Devel::Size $VERSION;
30 Devel::Size - Perl extension for finding the memory usage of Perl variables
34 use Devel::Size qw(size total_size);
36 my $size = size("A string");
38 my @foo = (1, 2, 3, 4, 5);
39 my $other_size = size(\@foo);
41 my $foo = {a => [1, 2, 3],
44 my $total_size = total_size($foo);
48 This module figures out the real sizes of Perl variables in bytes.
49 Call functions with a reference to the variable you want the size
50 of. If the variable is a plain scalar it returns the size of
51 the scalar. If the variable is a hash or an array, use a reference
58 The C<size> function returns the amount of memory the variable
59 returns. If the variable is a hash or an array, it only reports
60 the amount used by the structure, I<not> the contents.
62 =head2 total_size($ref)
64 The C<total_size> function will traverse the variable and look
65 at the sizes of contents. Any references contained in the variable
66 will also be followed, so this function can be used to get the
67 total size of a multidimensional data structure. At the moment
68 there is no way to get the size of an array or a hash and its
69 elements without using this function.
73 None but default, but optionally C<size> and C<total_size>.
75 =head1 UNDERSTANDING MEMORY ALLOCATION
77 Please note that the following discussion of memory allocation in perl
78 is based on the perl 5.8.0 sources. While this is generally
79 applicable to all versions of perl, some of the gory details are
80 omitted. It also makes some presumptions on how your system memory
81 allocator works so, while it will be generally correct, it may not
82 exactly reflect your system. (Generally the only issue is the size of
83 the constant values we'll talk about, not their existence)
87 It's important firtst to understand how your OS and libraries handle
88 memory. When the perl interpreter needs some memory, it asks the C
89 runtime library for it, using the C<malloc()> call. C<malloc> has one
90 parameter, the size of the memory allocation you want, and returns a
91 pointer to that memory. C<malloc> also makes sure that the pointer it
92 returns to you is properly aligned. When you're done with the memory
93 you hand it back to the library with the C<free()> call. C<free> has
94 one parameter, the pointer that C<malloc> returned. There are a couple of interesting ramifications to this.
96 Because malloc has to return an aligned pointer, it will round up the
97 memory allocation to make sure that the memory it returns is aligned
98 right. What that alignment is depends on your CPU, OS, and compiler
99 settings, but things are generally aligned to either a 4 or 8 byte
100 boundary. That means that if you ask for 1 byte, C<malloc> will
101 silently round up to either 4 or 8 bytes, though it doesn't tell the
102 program making the request, so the extra memory can't be used.
104 Since C<free> isn't given the size of the memory chunk you're
105 freeing, it has to track it another way. Most libraries do this by
106 tacking on a length field just before the memory it hands to your
107 program. (It's put before the beginning rather than after the end
108 because it's less likely to get mangled by program bugs) This size
109 field is the size of your platform integer, Generally either 4 or 8
112 So, if you asked for 1 byte, malloc would build something like this:
116 +------------------+ <----- the pointer malloc returns
122 As you can see, you asked for 1 byte but C<malloc> used 8. If your
123 integers were 8 bytes rather than 4, C<malloc> would have used 16 bytes
124 to satisfy your 1 byte request.
126 The C memory allocation system also keeps a list of free memory
127 chunks, so it can recycle freed memory. For performance reasons, some
128 C memory allocation systems put a limit to the number of free
129 segments that are on the free list, or only search through a small
130 number of memory chunks waiting to be recycled before just
131 allocating more memory from the system.
133 The memory allocation system tries to keep as few chunks on the free
134 list as possible. It does this by trying to notice if there are two
135 adjacent chunks of memory on the free list and, if there are,
136 coalescing them into a single larger chunk. This works pretty well,
137 but there are ways to have a lot of memory on the free list yet still
138 not have anything that can be allocated. If a program allocates one
139 million eight-byte chunks, for example, then frees every other chunk,
140 there will be four million bytes of memory on the free list, but none
141 of that memory can be handed out to satisfy a request for 10
142 bytes. This is what's referred to as a fragmented free list, and can
143 be one reason why your program could have a lot of free memory yet
144 still not be able to allocate more, or have a huge process size and
145 still have almost no memory actually allocated to the program running.
149 Perl's memory allocation scheme is a bit convoluted, and more complex
150 than can really be addressed here, but there is one common spot where Perl's
151 memory allocation is unintuitive, and that's for hash keys.
153 When you have a hash, each entry has a structure that points to the
154 key and the value for that entry. The value is just a pointer to the
155 scalar in the entry, and doesn't take up any special amount of
156 memory. The key structure holds the hash value for the key, the key
157 length, and the key string. (The entry and key structures are
158 separate so perl can potentially share keys across multiple hashes)
160 The entry structure has three pointers in it, and takes up either 12
161 or 24 bytes, depending on whether you're on a 32 bit or 64 bit
162 system. Since these structures are of fixed size, perl can keep a big
163 pool of them internally (generally called an arena) so it doesn't
164 have to allocate memory for each one.
166 The key structure, though, is of variable length because the key
167 string is of variable length, so perl has to ask the system for a
168 memory allocation for each key. The base size of this structure is
169 8 or 16 bytes (once again, depending on whether you're on a 32 bit or
170 64 bit system) plus the string length plus two bytes.
172 Since this memory has to be allocated from the system there's the
173 malloc size-field overhead (4 or 8 bytes) plus the alignment bytes (0
174 to 7, depending on your system and the key length)
175 that get added on to the chunk perl requests. If the key is only 1
176 character, and you're on a 32 bit system, the allocation will be 16
177 bytes. If the key is 7 characters then the allocation is 24 bytes on
178 a 32 bit system. If you're on a 64 bit system the numbers get even
181 This does mean that hashes eat up a I<lot> of memory, both in memory
182 Devel::Size can track (the memory actually in the structures and
183 strings) and that it can't (the malloc alignment and length overhead).
187 Devel::Size, because of the way it works, can consume a
188 considerable amount of memory as it runs. It will use five
189 pointers, two integers, and two bytes worth of storage, plus
190 potential alignment and bucket overhead, per thing it looks at. This
191 memory is released at the end, but it may fragment your free pool,
192 and will definitely expand your process' memory footprint.
194 =head1 Messages: texts originating from this module.
200 =item "Devel::Size: Unknown variable type"
202 The thing (or something contained within it) that you gave to
203 total_size() was unrecognisable as a Perl entity.
209 These messages warn you that for some types, the sizes calculated may not include
210 everything that could be associated with those types. The differences are usually
211 insignificant for most uses of this module.
213 These may be disabled by setting
215 $Devel::Size::warn = 0
219 =item "Devel::Size: Calculated sizes for CVs are incomplete"
221 =item "Devel::Size: Calculated sizes for FMs are incomplete"
227 Doesn't currently walk all the bits for code refs, formats, and
228 IO. Those throw a warning, but a minimum size for them is returned.
230 Devel::Size only counts the memory that perl actually allocates. It
231 doesn't count 'dark' memory--memory that is lost due to fragmented free lists,
232 allocation alignments, or C library overhead.
236 Dan Sugalski dan@sidhe.org
238 Small portion taken from the B module as shipped with perl 5.6.2.
240 Maintained now by Tels <http://bloodgate.com>
244 Copyright (C) 2005 Dan Sugalski.
245 Copyright (C) 2007 Tels
247 This module is free software; you can redistribute it and/or modify it
248 under the same terms as Perl itself.
252 perl(1), L<Devel::Size::Report>.