lib/Devel/Size.pm

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