1Devel::Size(3)        User Contributed Perl Documentation       Devel::Size(3)
2
3
4

NAME

6       Devel::Size - Perl extension for finding the memory usage of Perl
7       variables
8

SYNOPSIS

10         use Devel::Size qw(size total_size);
11
12         my $size = size("A string");
13
14         my @foo = (1, 2, 3, 4, 5);
15         my $other_size = size(\@foo);
16
17         my $foo = {a => [1, 2, 3],
18             b => {a => [1, 3, 4]}
19                };
20         my $total_size = total_size($foo);
21

DESCRIPTION

23       This module figures out the real size of Perl variables in bytes, as
24       accurately as possible.
25
26       Call functions with a reference to the variable you want the size of.
27       If the variable is a plain scalar it returns the size of this scalar.
28       If the variable is a hash or an array, use a reference when calling.
29

FUNCTIONS

31   size($ref)
32       The "size" function returns the amount of memory the variable returns.
33       If the variable is a hash or an array, it only reports the amount used
34       by the structure, not the contents.
35
36   total_size($ref)
37       The "total_size" function will traverse the variable and look at the
38       sizes of contents.  Any references contained in the variable will also
39       be followed, so this function can be used to get the total size of a
40       multidimensional data structure.  At the moment there is no way to get
41       the size of an array or a hash and its elements without using this
42       function.
43

EXPORT

45       None but default, but optionally "size" and "total_size".
46

UNDERSTANDING MEMORY ALLOCATION

48       Please note that the following discussion of memory allocation in perl
49       is based on the perl 5.8.0 sources. While this is generally applicable
50       to all versions of perl, some of the gory details are omitted. It also
51       makes some presumptions on how your system memory allocator works so,
52       while it will be generally correct, it may not exactly reflect your
53       system. (Generally the only issue is the size of the constant values
54       we'll talk about, not their existence)
55
56   The C library
57       It's important first to understand how your OS and libraries handle
58       memory. When the perl interpreter needs some memory, it asks the C
59       runtime library for it, using the "malloc()" call. "malloc" has one
60       parameter, the size of the memory allocation you want, and returns a
61       pointer to that memory. "malloc" also makes sure that the pointer it
62       returns to you is properly aligned. When you're done with the memory
63       you hand it back to the library with the "free()" call. "free" has one
64       parameter, the pointer that "malloc" returned.  There are a couple of
65       interesting ramifications to this.
66
67       Because malloc has to return an aligned pointer, it will round up the
68       memory allocation to make sure that the memory it returns is aligned
69       right. What that alignment is depends on your CPU, OS, and compiler
70       settings, but things are generally aligned to either a 4 or 8 byte
71       boundary. That means that if you ask for 1 byte, "malloc" will silently
72       round up to either 4 or 8 bytes, though it doesn't tell the program
73       making the request, so the extra memory can't be used.
74
75       Since "free" isn't given the size of the memory chunk you're freeing,
76       it has to track it another way. Most libraries do this by tacking on a
77       length field just before the memory it hands to your program. (It's put
78       before the beginning rather than after the end because it's less likely
79       to get mangled by program bugs) This size field is the size of your
80       platform integer, Generally either 4 or 8 bytes.
81
82       So, if you asked for 1 byte, malloc would build something like this:
83
84            +------------------+
85            | 4 byte length    |
86            +------------------+ <----- the pointer malloc returns
87            | your 1 byte      |
88            +------------------+
89            | 3 bytes padding  |
90            +------------------+
91
92       As you can see, you asked for 1 byte but "malloc" used 8. If your
93       integers were 8 bytes rather than 4, "malloc" would have used 16 bytes
94       to satisfy your 1 byte request.
95
96       The C memory allocation system also keeps a list of free memory chunks,
97       so it can recycle freed memory. For performance reasons, some C memory
98       allocation systems put a limit to the number of free segments that are
99       on the free list, or only search through a small number of memory
100       chunks waiting to be recycled before just allocating more memory from
101       the system.
102
103       The memory allocation system tries to keep as few chunks on the free
104       list as possible. It does this by trying to notice if there are two
105       adjacent chunks of memory on the free list and, if there are,
106       coalescing them into a single larger chunk. This works pretty well, but
107       there are ways to have a lot of memory on the free list yet still not
108       have anything that can be allocated. If a program allocates one million
109       eight-byte chunks, for example, then frees every other chunk, there
110       will be four million bytes of memory on the free list, but none of that
111       memory can be handed out to satisfy a request for 10 bytes. This is
112       what's referred to as a fragmented free list, and can be one reason why
113       your program could have a lot of free memory yet still not be able to
114       allocate more, or have a huge process size and still have almost no
115       memory actually allocated to the program running.
116
117   Perl
118       Perl's memory allocation scheme is a bit convoluted, and more complex
119       than can really be addressed here, but there is one common spot where
120       Perl's memory allocation is unintuitive, and that's for hash keys.
121
122       When you have a hash, each entry has a structure that points to the key
123       and the value for that entry. The value is just a pointer to the scalar
124       in the entry, and doesn't take up any special amount of memory. The key
125       structure holds the hash value for the key, the key length, and the key
126       string. (The entry and key structures are separate so perl can
127       potentially share keys across multiple hashes)
128
129       The entry structure has three pointers in it, and takes up either 12 or
130       24 bytes, depending on whether you're on a 32 bit or 64 bit system.
131       Since these structures are of fixed size, perl can keep a big pool of
132       them internally (generally called an arena) so it doesn't have to
133       allocate memory for each one.
134
135       The key structure, though, is of variable length because the key string
136       is of variable length, so perl has to ask the system for a memory
137       allocation for each key. The base size of this structure is 8 or 16
138       bytes (once again, depending on whether you're on a 32 bit or 64 bit
139       system) plus the string length plus two bytes.
140
141       Since this memory has to be allocated from the system there's the
142       malloc size-field overhead (4 or 8 bytes) plus the alignment bytes (0
143       to 7, depending on your system and the key length) that get added on to
144       the chunk perl requests. If the key is only 1 character, and you're on
145       a 32 bit system, the allocation will be 16 bytes. If the key is 7
146       characters then the allocation is 24 bytes on a 32 bit system. If
147       you're on a 64 bit system the numbers get even larger.
148

DANGERS

150       Since version 0.72, Devel::Size uses a new pointer tracking mechanism
151       that consumes far less memory than was previously the case. It does
152       this by using a bit vector where 1 bit represents each 4- or 8-byte
153       aligned pointer (32- or 64-bit platform dependent) that could exist.
154       Further, it segments that bit vector and only allocates each chunk when
155       an address is seen within that chunk. Since version 0.73, chunks are
156       allocated in blocks of 2**16 bits (ie 8K), accessed via a 256-way tree.
157       The tree is 2 levels deep on a 32 bit system, 6 levels deep on a 64 bit
158       system. This avoids having make any assumptions about address layout on
159       64 bit systems or trade offs about sizes to allocate. It assumes that
160       the addresses of allocated pointers are reasonably contiguous, so that
161       relevant parts of the tree stay in the CPU cache.
162
163       Besides saving a lot of memory, this change means that Devel::Size runs
164       significantly faster than previous versions.
165

Messages: texts originating from this module.

167   Errors
168       "Devel::Size: Unknown variable type"
169           The thing (or something contained within it) that you gave to
170           total_size() was unrecognisable as a Perl entity.
171
172   warnings
173       These messages warn you that for some types, the sizes calculated may
174       not include everything that could be associated with those types. The
175       differences are usually insignificant for most uses of this module.
176
177       These may be disabled by setting
178
179           $Devel::Size::warn = 0
180
181       "Devel::Size: Calculated sizes for CVs are incomplete"
182       "Devel::Size: Calculated sizes for FMs are incomplete"
183       "Devel::Size: Calculated sizes for compiled regexes are incompatible,
184       and probably always will be"
185
186   New warnings since 0.72
187       Devel::Size has always been vulnerable to trapping when traversing
188       Perl's internal data structures, if it encounters uninitialised
189       (dangling) pointers.
190
191       MSVC provides exception handling able to deal with this possibility,
192       and when built with MSVC Devel::Size will now attempt to ignore (or
193       log) them and continue. These messages are mainly of interest to
194       Devel::Size and core developers, and so are disabled by default.
195
196       They may be enabled by setting
197
198           $Devel::Size::dangle = 0
199
200       "Devel::Size: Can't determine class of operator OPx_XXXX, assuming
201       BASEOP\n"
202       "Devel::Size: Encountered bad magic at: 0xXXXXXXXX"
203       "Devel::Size: Encountered dangling pointer in opcode at: 0xXXXXXXXX"
204       "Devel::Size: Encountered invalid pointer: 0xXXXXXXXX"
205

BUGS

207       Doesn't currently walk all the bits for code refs, formats, and IO.
208       Those throw a warning, but a minimum size for them is returned.
209
210       Devel::Size only counts the memory that perl actually allocates. It
211       doesn't count 'dark' memory--memory that is lost due to fragmented free
212       lists, allocation alignments, or C library overhead.
213

AUTHOR

215       Dan Sugalski dan@sidhe.org
216
217       Small portion taken from the B module as shipped with perl 5.6.2.
218
219       Previously maintained by Tels <http://bloodgate.com>
220
221       New pointer tracking & exception handling for 0.72 by BrowserUK
222
223       Currently maintained by Nicholas Clark
224
226       Copyright (C) 2005 Dan Sugalski, Copyright (C) 2007-2008 Tels
227
228       This module is free software; you can redistribute it and/or modify it
229       under the same terms as Perl v5.8.8.
230

SEE ALSO

232       perl(1), Devel::Size::Report.
233
234
235
236perl v5.32.1                      2021-01-27                    Devel::Size(3)
Impressum