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 you an idea how much memory your program and libraries are using. Interfaces to some GNU C Library specific malloc information is 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. However normally almost all runtime space goes through malloc so it's close to the total, and dynamic usage is often what you're interested in anyway.

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 the 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 no particular 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 your 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.

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 plus hblkhd is the total bytes taken from the system. hblkhd is mmapped big blocks currently in use. arena space is from sbrk() and within that uordblks plus usmblks is currently in use, and fordblks plus fsmblks is free.

hblkhd space is immediately returned to the system when freed. arena space is shrunk when there's enough free at the top to be worth doing. keepcost is the current free bytes at the end which could be given back.

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. It goes to the C stderr, not Perl STDERR so in the unlikely event you added buffering to STDERR you might have to flush to keep output in sequence. (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 any UTF8 flag may be forcibly turned off by this action. 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 (via a temporary file, in the current implementation). 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 attempting a strict parse then note Glibc 2.10.1 and earlier was missing a couple of 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 is high then you can explicitly release some.

Glibc only frees whole pages, so if $bytes doesn't end up reducing by at least a whole page then the return will be 0. Glibc also notices if someone else has allocated memory with sbrk and it won't touch that.

OTHER NOTES

On a 64-bit system with a 32-bit C int type, the int fields in struct mallinfo may overflow and either 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.

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

HOME PAGE

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

LICENSE

Devel-Mallinfo is Copyright 2007, 2008, 2009, 2010 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/>.

cpanm Devel::Mallinfo

perl -MCPAN -e shell
install Devel::Mallinfo