mallinfo(3) man page for review

mallinfo(3) man page for review

[Michael Kerrisk (man-pages)]

[-- Attachment #1: Type: text/plain, Size: 9111 bytes --]

I've written the man page page below to document glibc's mallinfo(3).
Review comments welcome!

Cheers,

Michael

'\" t
.\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\"
.TH MALLINFO 3  2012-04-28 "Linux" "Linux Programmer's Manual"
.SH NAME
mallinfo \- obtain memory allocation information
.SH SYNOPSIS
.B #include <malloc.h>

.B struct mallinfo mallinfo(void);
.SH DESCRIPTION
The
.BR mallinfo ()
function returns a copy of a structure containing information about
memory allocations performed by
.BR malloc (3)
and related functions.
This structure is defined as follows:
.PP
.in +4n
.nf
struct mallinfo {
    int arena;     /* Non-mmapped space allocated (bytes) */
    int ordblks;   /* Number of free chunks */
    int smblks;    /* Number of free fastbin blocks */
    int hblks;     /* Number of mmapped regions */
    int hblkhd;    /* Space allocated in mmapped regions (bytes) */
    int usmblks;   /* Maximum total allocated space (bytes) */
    int fsmblks;   /* Space in freed fastbin blocks (bytes) */
    int uordblks;  /* Total allocated space (bytes) */
    int fordblks;  /* Total free space (bytes) */
    int keepcost;  /* Top-most, releasable space (bytes) */
};
.fi
.in
.PP
The fields of the
.I mallinfo
structure contain the following information:

.TP 10
.I arena
The total amount of memory allocated by means other than
.BR mmap (2)
(i.e., memory allocated on the heap).
This figure includes both in-use blocks and blocks on the free list.
.TP
.I ordblks
The number of ordinary (i.e., non-fastbin) free blocks.
.TP
.I smblks
The number of fastbin free blocks (see
.BR mallopt (3)).
.TP
.I hblks
The number of blocks currently allocated using
.BR mmap (2).
.TP
.I hblkhd
The number of bytes in blocks currently allocated using
.BR mmap (2).
.TP
.I usmblks
The "highwater mark" for allocated space\(emthat is,
the maximum amount of space that was ever allocated.
This field is maintained only in nonthreading environments.
.TP
.I fsmblks
The total number of bytes in fastbin free blocks.
.TP
.I uordblks
The total number of bytes used by in-use allocations.
.TP
.I fordblks
The total number of bytes in free blocks.
.TP
.I keepcost
The total amount of releasable free space at the top
of the heap.
This is the maximum number of bytes that could ideally
(i.e., ignoring page alignment restrictions, and so on) be released by
.BR malloc_trim (3).
.\" .SH VERSIONS
.\" Available already in glibc 2.0, possibly earlier
.SH CONFORMING TO
This function is not specified by POSIX or the C standards.
A similar function exists on many System V derivatives,
and was specified in the SVID.
.SH BUGS
.\" FIXME http://sourceware.org/bugzilla/show_bug.cgi?id=208
.\" See the 24 Aug 2011 mail by Paul Pluzhnikov:
.\"     "[patch] Fix mallinfo() to accumulate results for all arenas"
.\" on libc-alpha-9JcytcrH/bA+uJoB2kUjGw@public.gmane.org
.B Information is returned for only the main memory allocation area.
Allocations in other arenas are excluded.
See
.BR malloc_stats (3)
and
.BR malloc_info (3)
for alternatives that include information about other arenas.

The fields of the
.I mallinfo
structure are typed as
.IR int .
However, because some internal bookkeeping values may be of type
.IR long ,
the reported values may wrap around zero and thus be inaccurate.
.SH EXAMPLE
The program below employs
.BR mallinfo ()
to retrieve memory allocation statistics before and after
allocating and freeing some blocks of memory.
The statistics are displayed on standard output.

The first two command-line arguments specify the number and size of
blocks to be allocated with
.BR malloc (3).

The remaining three arguments specify which of the allocated blocks
should be freed with
.BR free (3).
These three arguments are optional, and specify (in order):
the step size to be used in the loop that frees blocks
(the default is 1, meaning free all blocks in the range);
the ordinal position of the first block to be freed
(default 0, meaning the first allocated block);
and a number one greater than the ordinal position
of the last block to be freed
(default is one greater than the maximum block number).
If these three arguments are omitted,
then the defaults cause all allocated blocks to be freed.

In the following example run of the program,
1000 allocations of 100 bytes are performed,
and then every second allocated block is freed:
.PP
.in +4n
.nf
$ \fB./a.out 1000 100 2\fP
============== Before allocating blocks ==============
Total non\-mmapped bytes (arena):       0
# of free chunks (ordblks):            1
# of free fastbin blocks (smblks):     0
# of mapped regions (hblks):           0
Bytes in mapped regions (hblkhd):      0
Max. total allocated space (usmblks):  0
Free bytes held in fastbins (fsmblks): 0
Total allocated space (uordblks):      0
Total free space (fordblks):           0
Topmost releasable block (keepcost):   0

============== After allocating blocks ==============
Total non\-mmapped bytes (arena):       135168
# of free chunks (ordblks):            1
# of free fastbin blocks (smblks):     0
# of mapped regions (hblks):           0
Bytes in mapped regions (hblkhd):      0
Max. total allocated space (usmblks):  0
Free bytes held in fastbins (fsmblks): 0
Total allocated space (uordblks):      104000
Total free space (fordblks):           31168
Topmost releasable block (keepcost):   31168

============== After freeing blocks ==============
Total non\-mmapped bytes (arena):       135168
# of free chunks (ordblks):            501
# of free fastbin blocks (smblks):     0
# of mapped regions (hblks):           0
Bytes in mapped regions (hblkhd):      0
Max. total allocated space (usmblks):  0
Free bytes held in fastbins (fsmblks): 0
Total allocated space (uordblks):      52000
Total free space (fordblks):           83168
Topmost releasable block (keepcost):   31168
.fi
.in
.SS Program source
\&
.nf
#include <malloc.h>
#include "tlpi_hdr.h"

static void
display_mallinfo(void)
{
    struct mallinfo mi;

    mi = mallinfo();

    printf("Total non\-mmapped bytes (arena):       %d\\n", mi.arena);
    printf("# of free chunks (ordblks):            %d\\n", mi.ordblks);
    printf("# of free fastbin blocks (smblks):     %d\\n", mi.smblks);
    printf("# of mapped regions (hblks):           %d\\n", mi.hblks);
    printf("Bytes in mapped regions (hblkhd):      %d\\n", mi.hblkhd);
    printf("Max. total allocated space (usmblks):  %d\\n", mi.usmblks);
    printf("Free bytes held in fastbins (fsmblks): %d\\n", mi.fsmblks);
    printf("Total allocated space (uordblks):      %d\\n", mi.uordblks);
    printf("Total free space (fordblks):           %d\\n", mi.fordblks);
    printf("Topmost releasable block (keepcost):   %d\\n", mi.keepcost);
}

int
main(int argc, char *argv[])
{
#define MAX_ALLOCS 2000000
    char *alloc[MAX_ALLOCS];
    int numBlocks, j, freeBegin, freeEnd, freeStep;
    size_t blockSize;

    if (argc < 3 || strcmp(argv[1], "\-\-help") == 0)
        usageErr("%s num\-blocks block\-size [free\-step [start\-free "
                "[end\-free]]]\\n", argv[0]);

    numBlocks = atoi(argv[1]);
    blockSize = atoi(argv[2]);
    freeStep = (argc > 3) ? atoi(argv[3]) : 1;
    freeBegin = (argc > 4) ? atoi(argv[4]) : 0;
    freeEnd = (argc > 5) ? atoi(argv[5]) : numBlocks;

    printf("============== Before allocating blocks ==============\\n");
    display_mallinfo();

    for (j = 0; j < numBlocks; j++) {
        if (numBlocks >= MAX_ALLOCS)
            fatal("Too many allocations");

        alloc[j] = malloc(blockSize);
        if (alloc[j] == NULL)
            errExit("malloc");
    }

    printf("\\n============== After allocating blocks ==============\\n");
    display_mallinfo();

    for (j = freeBegin; j < freeEnd; j += freeStep)
        free(alloc[j]);

    printf("\\n============== After freeing blocks ==============\\n");
    display_mallinfo();

    exit(EXIT_SUCCESS);
}
.fi
.SH SEE ALSO
.ad l
.nh
.BR mmap (2),
.BR malloc (3),
.BR malloc_info (3),
.BR malloc_stats (3),
.BR malloc_trim (3),
.BR mallopt (3)

[-- Attachment #2: mallinfo.3 --]
[-- Type: application/octet-stream, Size: 8942 bytes --]

'\" t
.\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\"
.TH MALLINFO 3  2012-04-28 "Linux" "Linux Programmer's Manual"
.SH NAME
mallinfo \- obtain memory allocation information
.SH SYNOPSIS
.B #include <malloc.h>

.B struct mallinfo mallinfo(void);
.SH DESCRIPTION
The
.BR mallinfo ()
function returns a copy of a structure containing information about
memory allocations performed by
.BR malloc (3)
and related functions.
This structure is defined as follows:
.PP
.in +4n
.nf
struct mallinfo {
    int arena;     /* Non-mmapped space allocated (bytes) */
    int ordblks;   /* Number of free chunks */
    int smblks;    /* Number of free fastbin blocks */
    int hblks;     /* Number of mmapped regions */
    int hblkhd;    /* Space allocated in mmapped regions (bytes) */
    int usmblks;   /* Maximum total allocated space (bytes) */
    int fsmblks;   /* Space in freed fastbin blocks (bytes) */
    int uordblks;  /* Total allocated space (bytes) */
    int fordblks;  /* Total free space (bytes) */
    int keepcost;  /* Top-most, releasable space (bytes) */
};
.fi
.in
.PP
The fields of the
.I mallinfo
structure contain the following information:

.TP 10
.I arena
The total amount of memory allocated by means other than
.BR mmap (2)
(i.e., memory allocated on the heap).
This figure includes both in-use blocks and blocks on the free list.
.TP
.I ordblks
The number of ordinary (i.e., non-fastbin) free blocks.
.TP
.I smblks
The number of fastbin free blocks (see
.BR mallopt (3)).
.TP
.I hblks
The number of blocks currently allocated using
.BR mmap (2).
.TP
.I hblkhd
The number of bytes in blocks currently allocated using
.BR mmap (2).
.TP
.I usmblks
The "highwater mark" for allocated space\(emthat is,
the maximum amount of space that was ever allocated.
This field is maintained only in nonthreading environments.
.TP
.I fsmblks
The total number of bytes in fastbin free blocks.
.TP
.I uordblks
The total number of bytes used by in-use allocations.
.TP
.I fordblks
The total number of bytes in free blocks.
.TP
.I keepcost
The total amount of releasable free space at the top
of the heap.
This is the maximum number of bytes that could ideally
(i.e., ignoring page alignment restrictions, and so on) be released by
.BR malloc_trim (3).
.\" .SH VERSIONS
.\" Available already in glibc 2.0, possibly earlier
.SH CONFORMING TO
This function is not specified by POSIX or the C standards.
A similar function exists on many System V derivatives,
and was specified in the SVID.
.SH BUGS
.\" FIXME http://sourceware.org/bugzilla/show_bug.cgi?id=208
.\" See the 24 Aug 2011 mail by Paul Pluzhnikov:
.\"     "[patch] Fix mallinfo() to accumulate results for all arenas"
.\" on libc-alpha@sourceware.org
.B Information is returned for only the main memory allocation area.
Allocations in other arenas are excluded.
See
.BR malloc_stats (3)
and
.BR malloc_info (3)
for alternatives that include information about other arenas.

The fields of the
.I mallinfo
structure are typed as
.IR int .
However, because some internal bookkeeping values may be of type
.IR long ,
the reported values may wrap around zero and thus be inaccurate.
.SH EXAMPLE
The program below employs
.BR mallinfo ()
to retrieve memory allocation statistics before and after
allocating and freeing some blocks of memory.
The statistics are displayed on standard output.

The first two command-line arguments specify the number and size of
blocks to be allocated with
.BR malloc (3).

The remaining three arguments specify which of the allocated blocks
should be freed with
.BR free (3).
These three arguments are optional, and specify (in order):
the step size to be used in the loop that frees blocks
(the default is 1, meaning free all blocks in the range);
the ordinal position of the first block to be freed
(default 0, meaning the first allocated block);
and a number one greater than the ordinal position
of the last block to be freed
(default is one greater than the maximum block number).
If these three arguments are omitted,
then the defaults cause all allocated blocks to be freed.

In the following example run of the program,
1000 allocations of 100 bytes are performed,
and then every second allocated block is freed:
.PP
.in +4n
.nf
$ \fB./a.out 1000 100 2\fP
============== Before allocating blocks ==============
Total non\-mmapped bytes (arena):       0
# of free chunks (ordblks):            1
# of free fastbin blocks (smblks):     0
# of mapped regions (hblks):           0
Bytes in mapped regions (hblkhd):      0
Max. total allocated space (usmblks):  0
Free bytes held in fastbins (fsmblks): 0
Total allocated space (uordblks):      0
Total free space (fordblks):           0
Topmost releasable block (keepcost):   0

============== After allocating blocks ==============
Total non\-mmapped bytes (arena):       135168
# of free chunks (ordblks):            1
# of free fastbin blocks (smblks):     0
# of mapped regions (hblks):           0
Bytes in mapped regions (hblkhd):      0
Max. total allocated space (usmblks):  0
Free bytes held in fastbins (fsmblks): 0
Total allocated space (uordblks):      104000
Total free space (fordblks):           31168
Topmost releasable block (keepcost):   31168

============== After freeing blocks ==============
Total non\-mmapped bytes (arena):       135168
# of free chunks (ordblks):            501
# of free fastbin blocks (smblks):     0
# of mapped regions (hblks):           0
Bytes in mapped regions (hblkhd):      0
Max. total allocated space (usmblks):  0
Free bytes held in fastbins (fsmblks): 0
Total allocated space (uordblks):      52000
Total free space (fordblks):           83168
Topmost releasable block (keepcost):   31168
.fi
.in
.SS Program source
\&
.nf
#include <malloc.h>
#include "tlpi_hdr.h"

static void
display_mallinfo(void)
{
    struct mallinfo mi;

    mi = mallinfo();

    printf("Total non\-mmapped bytes (arena):       %d\\n", mi.arena);
    printf("# of free chunks (ordblks):            %d\\n", mi.ordblks);
    printf("# of free fastbin blocks (smblks):     %d\\n", mi.smblks);
    printf("# of mapped regions (hblks):           %d\\n", mi.hblks);
    printf("Bytes in mapped regions (hblkhd):      %d\\n", mi.hblkhd);
    printf("Max. total allocated space (usmblks):  %d\\n", mi.usmblks);
    printf("Free bytes held in fastbins (fsmblks): %d\\n", mi.fsmblks);
    printf("Total allocated space (uordblks):      %d\\n", mi.uordblks);
    printf("Total free space (fordblks):           %d\\n", mi.fordblks);
    printf("Topmost releasable block (keepcost):   %d\\n", mi.keepcost);
}

int
main(int argc, char *argv[])
{
#define MAX_ALLOCS 2000000
    char *alloc[MAX_ALLOCS];
    int numBlocks, j, freeBegin, freeEnd, freeStep;
    size_t blockSize;

    if (argc < 3 || strcmp(argv[1], "\-\-help") == 0)
        usageErr("%s num\-blocks block\-size [free\-step [start\-free "
                "[end\-free]]]\\n", argv[0]);

    numBlocks = atoi(argv[1]);
    blockSize = atoi(argv[2]);
    freeStep = (argc > 3) ? atoi(argv[3]) : 1;
    freeBegin = (argc > 4) ? atoi(argv[4]) : 0;
    freeEnd = (argc > 5) ? atoi(argv[5]) : numBlocks;

    printf("============== Before allocating blocks ==============\\n");
    display_mallinfo();

    for (j = 0; j < numBlocks; j++) {
        if (numBlocks >= MAX_ALLOCS)
            fatal("Too many allocations");

        alloc[j] = malloc(blockSize);
        if (alloc[j] == NULL)
            errExit("malloc");
    }

    printf("\\n============== After allocating blocks ==============\\n");
    display_mallinfo();

    for (j = freeBegin; j < freeEnd; j += freeStep)
        free(alloc[j]);

    printf("\\n============== After freeing blocks ==============\\n");
    display_mallinfo();

    exit(EXIT_SUCCESS);
}
.fi
.SH SEE ALSO
.ad l
.nh
.BR mmap (2),
.BR malloc (3),
.BR malloc_info (3),
.BR malloc_stats (3),
.BR malloc_trim (3),
.BR mallopt (3)

Re: mallinfo(3) man page for review

[KOSAKI Motohiro]

Hi

On Fri, May 4, 2012 at 8:08 PM, Michael Kerrisk (man-pages)
<mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> I've written the man page page below to document glibc's mallinfo(3).
> Review comments welcome!
>
> Cheers,
>
> Michael

I don't find any issue. a few nit are below.


> .TP 10
> .I arena
> The total amount of memory allocated by means other than
> .BR mmap (2)
> (i.e., memory allocated on the heap).
> This figure includes both in-use blocks and blocks on the free list.
> .TP
> .I ordblks
> The number of ordinary (i.e., non-fastbin) free blocks.
> .TP
> .I smblks
> The number of fastbin free blocks (see
> .BR mallopt (3)).

It would be nice if a meaning of fastbin was described here.
It is allocation cache (for increasing cpu cache hit ratio) from
point of bird view.

> .TP
> .I hblks
> The number of blocks currently allocated using
> .BR mmap (2).

It would be nice if glibc malloc try to allocate memory by using mmap directly
if size is greater than MMAP_THRESHOLD.

Also nice if refer mallopt and MMAP_THRESHOLD.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: mallinfo(3) man page for review

[Michael Kerrisk (man-pages)]

Motohiro,

Thank you for taking the time to look at this.

On Sun, May 6, 2012 at 9:25 AM, KOSAKI Motohiro
<kosaki.motohiro-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> Hi
>
> On Fri, May 4, 2012 at 8:08 PM, Michael Kerrisk (man-pages)
> <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>> I've written the man page page below to document glibc's mallinfo(3).
>> Review comments welcome!
>>
>> Cheers,
>>
>> Michael
>
> I don't find any issue. a few nit are below.
>
>
>> .TP 10
>> .I arena
>> The total amount of memory allocated by means other than
>> .BR mmap (2)
>> (i.e., memory allocated on the heap).
>> This figure includes both in-use blocks and blocks on the free list.
>> .TP
>> .I ordblks
>> The number of ordinary (i.e., non-fastbin) free blocks.
>> .TP
>> .I smblks
>> The number of fastbin free blocks (see
>> .BR mallopt (3)).
>
> It would be nice if a meaning of fastbin was described here.
> It is allocation cache (for increasing cpu cache hit ratio) from
> point of bird view.

In the new mallopt(3) that is part of the next man-pages release,
there is this text on fastbins:

       M_MXFAST (since glibc 2.3)
              Set the upper limit for memory allocation requests  that
              are  satisfied  using "fastbins".  (The measurement unit
              for this parameter  is  bytes.)   Fastbins  are  storage
              areas that hold deallocated blocks of memory of the same
              size without merging adjacent free  blocks.   Subsequent
              reallocation  of  blocks of the same size can be handled
              very quickly by allocating from  the  fastbin,  although
              memory fragmentation and the overall memory footprint of
              the program can increase.  The default  value  for  this
              parameter  is  64*sizeof(size_t)/4  (i.e.,  64 on 32-bit
              architectures).  The range for this parameter  is  0  to
              80*sizeof(size_t)/4.  Setting M_MXFAST to 0 disables the
              use of fastbins.

Probably this is sufficient?

>> .TP
>> .I hblks
>> The number of blocks currently allocated using
>> .BR mmap (2).
>
> It would be nice if glibc malloc try to allocate memory by using mmap directly
> if size is greater than MMAP_THRESHOLD.
>
> Also nice if refer mallopt and MMAP_THRESHOLD.

Good idea. I added:

[[
(See the discussion of
.B M_MMAP_THRESHOLD
in
.BR mallopt (3).)
]]

In the new mallopt(3) page, there is then this text:

       M_MMAP_THRESHOLD
              For allocations greater than or equal to the limit spec‐
              ified  (in bytes) by M_MMAP_THRESHOLD that can't be sat‐
              isfied from the free list, the  memory-allocation  func‐
              tions  employ  mmap(2) instead of increasing the program
              break using sbrk(2).

              Allocating memory  using  mmap(2)  has  the  significant
              advantage that the allocated memory blocks can always be
              independently released back to  the  system.   (By  con‐
              trast,  the  heap can be trimmed only if memory is freed
              at the top end.)  On the other hand, there are some dis‐
              advantages  to  the use of mmap(2): deallocated space is
              not placed on the free list for reuse by  later  alloca‐
              tions;  memory may be wasted because mmap(2) allocations
              must be page-aligned; and the kernel  must  perform  the
              expensive  task  of  zeroing  out  memory  allocated via
              mmap(2).  Balancing these factors  leads  to  a  default
              setting of 128*1024 for the M_MMAP_THRESHOLD parameter.

              The  lower  limit  for  this  parameter is 0.  The upper
              limit is DEFAULT_MMAP_THRESHOLD_MAX: 512*1024 on  32-bit
              systems or 4*1024*1024*sizeof(long) on 64-bit systems.

              Note:  Nowadays,  glibc uses a dynamic mmap threshold by
              default.   The  initial  value  of  the   threshold   is
              128*1024,  but  when  blocks  larger  than  the  current
              threshold and less than or equal to DEFAULT_MMAP_THRESH‐
              OLD_MAX  are freed, the threshold is adjusted upwards to
              the size of the freed block.  When dynamic mmap  thresh‐
              olding is in effect, the threshold for trimming the heap
              is also dynamically adjusted to  be  twice  the  dynamic
              mmap  threshold.  Dynamic adjustment of the mmap thresh‐
              old  is  disabled  if  any  of   the   M_TRIM_THRESHOLD,
              M_TOP_PAD, M_MMAP_THRESHOLD, or M_MMAP_MAX parameters is
              set.

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: mallinfo(3) man page for review

[KOSAKI Motohiro]

(5/5/12 5:50 PM), Michael Kerrisk (man-pages) wrote:
> Motohiro,
>
> Thank you for taking the time to look at this.
>
> On Sun, May 6, 2012 at 9:25 AM, KOSAKI Motohiro
> <kosaki.motohiro-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>  wrote:
>> Hi
>>
>> On Fri, May 4, 2012 at 8:08 PM, Michael Kerrisk (man-pages)
>> <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>  wrote:
>>> I've written the man page page below to document glibc's mallinfo(3).
>>> Review comments welcome!
>>>
>>> Cheers,
>>>
>>> Michael
>>
>> I don't find any issue. a few nit are below.
>>
>>
>>> .TP 10
>>> .I arena
>>> The total amount of memory allocated by means other than
>>> .BR mmap (2)
>>> (i.e., memory allocated on the heap).
>>> This figure includes both in-use blocks and blocks on the free list.
>>> .TP
>>> .I ordblks
>>> The number of ordinary (i.e., non-fastbin) free blocks.
>>> .TP
>>> .I smblks
>>> The number of fastbin free blocks (see
>>> .BR mallopt (3)).
>>
>> It would be nice if a meaning of fastbin was described here.
>> It is allocation cache (for increasing cpu cache hit ratio) from
>> point of bird view.
>
> In the new mallopt(3) that is part of the next man-pages release,
> there is this text on fastbins:
>
>         M_MXFAST (since glibc 2.3)
>                Set the upper limit for memory allocation requests  that
>                are  satisfied  using "fastbins".  (The measurement unit
>                for this parameter  is  bytes.)   Fastbins  are  storage
>                areas that hold deallocated blocks of memory of the same
>                size without merging adjacent free  blocks.   Subsequent
>                reallocation  of  blocks of the same size can be handled
>                very quickly by allocating from  the  fastbin,  although
>                memory fragmentation and the overall memory footprint of
>                the program can increase.  The default  value  for  this
>                parameter  is  64*sizeof(size_t)/4  (i.e.,  64 on 32-bit
>                architectures).  The range for this parameter  is  0  to
>                80*sizeof(size_t)/4.  Setting M_MXFAST to 0 disables the
>                use of fastbins.
>
> Probably this is sufficient?

Yes, very good. can you please refer mallopt here?


>>> .TP
>>> .I hblks
>>> The number of blocks currently allocated using
>>> .BR mmap (2).
>>
>> It would be nice if glibc malloc try to allocate memory by using mmap directly
>> if size is greater than MMAP_THRESHOLD.
>>
>> Also nice if refer mallopt and MMAP_THRESHOLD.
>
> Good idea. I added:
>
> [[
> (See the discussion of
> .B M_MMAP_THRESHOLD
> in
> .BR mallopt (3).)
> ]]
>
> In the new mallopt(3) page, there is then this text:
>
>         M_MMAP_THRESHOLD
>                For allocations greater than or equal to the limit spec‐
>                ified  (in bytes) by M_MMAP_THRESHOLD that can't be sat‐
>                isfied from the free list, the  memory-allocation  func‐
>                tions  employ  mmap(2) instead of increasing the program
>                break using sbrk(2).
>
>                Allocating memory  using  mmap(2)  has  the  significant
>                advantage that the allocated memory blocks can always be
>                independently released back to  the  system.   (By  con‐
>                trast,  the  heap can be trimmed only if memory is freed
>                at the top end.)  On the other hand, there are some dis‐
>                advantages  to  the use of mmap(2): deallocated space is
>                not placed on the free list for reuse by  later  alloca‐
>                tions;  memory may be wasted because mmap(2) allocations
>                must be page-aligned; and the kernel  must  perform  the
>                expensive  task  of  zeroing  out  memory  allocated via
>                mmap(2).  Balancing these factors  leads  to  a  default
>                setting of 128*1024 for the M_MMAP_THRESHOLD parameter.
>
>                The  lower  limit  for  this  parameter is 0.  The upper
>                limit is DEFAULT_MMAP_THRESHOLD_MAX: 512*1024 on  32-bit
>                systems or 4*1024*1024*sizeof(long) on 64-bit systems.
>
>                Note:  Nowadays,  glibc uses a dynamic mmap threshold by
>                default.   The  initial  value  of  the   threshold   is
>                128*1024,  but  when  blocks  larger  than  the  current
>                threshold and less than or equal to DEFAULT_MMAP_THRESH‐
>                OLD_MAX  are freed, the threshold is adjusted upwards to
>                the size of the freed block.  When dynamic mmap  thresh‐
>                olding is in effect, the threshold for trimming the heap
>                is also dynamically adjusted to  be  twice  the  dynamic
>                mmap  threshold.  Dynamic adjustment of the mmap thresh‐
>                old  is  disabled  if  any  of   the   M_TRIM_THRESHOLD,
>                M_TOP_PAD, M_MMAP_THRESHOLD, or M_MMAP_MAX parameters is
>                set.

very nice!

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html