/ 
Devel-Mallinfo-14
River stage one • 1 direct dependent • 4 total dependents
/ Devel::Mallinfo

NAME

Devel::Mallinfo -- mallinfo() memory statistics and more

SYNOPSIS

use Devel::Mallinfo;
my $hashref = Devel::Mallinfo::mallinfo();
print "uordblks used space ", $hashref->{'uordblks'}, "\n";

Devel::Mallinfo::malloc_stats();  # GNU systems

DESCRIPTION

Devel::Mallinfo is an interface to the C library mallinfo() function giving various totals for memory used by malloc(). It's meant for development use, to give an idea how much memory a program and libraries are using. Interfaces to some GNU C Library specific malloc information are provided too, when available.

malloc() isn't the only way memory may be used. Program and library data and bss segments and the occasional direct mmap() don't show up in mallinfo(). But normally almost all runtime space goes through malloc() so it's close to the total and dynamic usage is often what's of interest anyway.

See the examples directory in the Devel-Mallinfo sources for some programs printing malloc info.

EXPORTS

Nothing is exported by default. Call with fully qualified function names or import in the usual way (see Exporter),

use Devel::Mallinfo 'mallinfo';
$h = mallinfo();

":all" imports everything

use Devel::Mallinfo ':all';
mallinfo_stats();  # on a GNU system

FUNCTIONS

$hashref = Devel::Mallinfo::mallinfo()

Return a reference to a hash of struct mallinfo values obtained from mallinfo(). The keys are field name strings and the values are integers. For example

{ 'arena'    => 16384,
  'uordblks' => 1234,
  ...
}

So to print (in random order)

my $info = Devel::Mallinfo::mallinfo();
foreach my $field (keys %$info) {
  print "$field is $info->{$field}\n";
}

Field names are grepped from struct mallinfo in malloc.h at build time, so everything on the system should be available. If mallinfo() is not available at all in whatever malloc() library Perl is using then mallinfo() returns a reference to an empty hash.

A new hash is created and returned each time, so later calls don't change previously returned info.

Fields

See the mallinfo() man page or the GNU C Library Reference Manual section "Statistics for Memory Allocation with `malloc'" for details of what the fields mean. On a modern system,

arena         bytes from sbrk()
hblkhd        bytes from mmap()

within the arena amount:

uordblks      bytes in use, ordinary blocks
usmblks       bytes in use, small blocks
fordblks      free bytes, ordinary blocks
fsmblks       free bytes, small blocks
keepcost      part of fordblks or fsmblks at top

totals:

arena+hblkhd             total taken from the system
uordblks+usmblks+hblkhd  total in use by program
fordblks+fsmblks         total free within program

hblkhd mmapped space is immediately returned to the system when freed. arena sbrk space is only shrunk when there's enough free at the top to be worth shrinking. keepcost is the current bytes there. Usually free() automatically shrinks when keepcost exceeds M_TRIM_THRESHOLD from mallopt(), for example 128 kbytes.

EXTRA FUNCTIONS

GNU C Library

The following are available in recent versions of the GNU C Library. If not available then they're not provided by Devel::Mallinfo.

Devel::Mallinfo::malloc_stats()

Print a malloc usage summary to standard error.

malloc_stats() uses C stderr, not Perl STDERR, so in the unlikely event Perl STDERR is buffered you might have to flush to keep output in sequence. (Perl's STDERR is unbuffered by default.)

$status = Devel::Mallinfo::malloc_info ($options, $fh)
$str = Devel::Mallinfo::malloc_info_string ($options)

Print malloc usage information to file handle $fh, or return it as a string $str. There are no $options values yet and that parameter should be 0.

malloc_info() returns 0 on success. It writes to $fh as a C FILE*, so PerlIO layers are ignored and a the XSUB casting might forcibly turn off any UTF8 flag. Perhaps this will improve in the future.

Devel::Mallinfo::malloc_info(0,\*STDOUT) == 0
  or die "oops, malloc_info() error";

malloc_info_string() is an extra in Devel::Mallinfo getting the output as a string (currently implemented through a temporary file). On error it returns undef and sets errno $!.

my $str = Devel::Mallinfo::malloc_info_string(0)
  // die "Cannot get malloc_info(), error: $!";

The output is vaguely XML and has more detail than mallinfo() gives. If doing a strict parse then note Glibc 2.10.1 and earlier missed some closing quotes in the final "<system>" elements.

$status = Devel::Mallinfo::malloc_trim ($bytes)

Trim free space at the top of the arena down to $bytes. Return 1 if memory was freed, 0 if not. Normally free() itself trims when there's enough to be worth releasing, but if you think the keepcost which is the space there is too high then you can explicitly release some.

Glibc only frees whole pages (sysconf(_SC_PAGESIZE) bytes), so if reducing to $bytes doesn't free at least one whole page then the return will be 0. Glibc also notices if something else in the program has allocated memory with sbrk() and it won't free that.

BUGS

On a 64-bit system with a 32-bit C int type, the int fields in struct mallinfo may overflow and wrap around to small or negative values, or maybe cap at INT_MAX. This is a known C library problem and Devel::Mallinfo doesn't try to do anything about it.

The mallopt() function would be a logical companion to mallinfo(), but generally it must be called before the first ever malloc(), so anything at the Perl level is much too late. Similarly mcheck() to enable consistency checks would have to be before the first ever malloc().

SEE ALSO

mallinfo(3), GNU C Library Manual "Statistics for Memory Allocation with `malloc'"

"Memory footprint debugging" in Devel::Peek, for statistics if using Perl's builtin malloc()

Memory::Usage

HOME PAGE

http://user42.tuxfamily.org/devel-mallinfo/index.html

LICENSE

Devel-Mallinfo is Copyright 2007, 2008, 2009, 2010, 2011, 2014 Kevin Ryde

Devel-Mallinfo is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

Devel-Mallinfo is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Devel-Mallinfo. If not, see <http://www.gnu.org/licenses/>.