LDP
/
man-pages
mirror of https://github.com/mkerrisk/man-pages
0
1
Fork 0
Code Releases Activity

mallopt.3: Document M_ARENA_TEST and M_ARENA_MAX 

In 2013 I brought up the discussion if M_ARENA_MAX and M_ARENA_TEST
were public parameters:
https://sourceware.org/ml/libc-alpha/2013-03/msg00376.html
Consensus among Siddhesh and myself was that they should be
public, and in fact they were already in the public header.
Therefore there may already be applications uses these constants
and expecting them to work. At best we could limit mallopt()'s
acceptance of the options, but that seems like a bad solution
that could lead to unexpected behavior for user applications.
A quick google search shows that there are packages relying on
these constants to tune the glibc malloc implementation.

Since glibc 2.10 the M_ARENA_TEST and M_ARENA_MAX features
have been part of the public interface with
--enable-experimental-malloc.

Since glibc 2.15 the experimental allocator has been on by default
and M_ARENA_TEST and M_ARENA_MAX have been more broadly used.

There are environment variables, without trailing underscore, that
can also be used to adjust these values at runtime i.e.
MALLOC_ARENA_MAX, and MALLOC_ARENA_TEST.

This change describes these two options in the mallopt(3) man page
along with their environment variables.

Tested with glibc master on x86_64 to verify it works as expected.

Signed-off-by: Carlos O'Donell <carlos@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Carlos O'Donell 2015-08-24 12:05:02 -04:00 committed by Michael Kerrisk
parent 3f81631283
commit 9d116bd272
1 changed files with 42 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
man3/mallopt.3
View File

@ -45,6 +45,36 @@ specifies the new value for that parameter.
The following values can be specified for
.IR param :
.TP
.BR M_ARENA_MAX
is the maximum number of arenas that can be created. The value of
M_ARENA_TEST is not used when M_ARENA_MAX is defined.
An arena represents a pool of memory that can be used by malloc
calls to service allocation requests. Arenas are thread safe and
therefore may have multiple concurrent memory requests. The
trade-off is between number of threads and number of arenas.
The more arenas you have the lower the per-thread contention,
but the higher the memory usage.
This parameter has been available since glibc 2.10 via
--enable-experimental-malloc, or glibc 2.15 by default.
In some versions of the allocator there was no limit on the number
of created arenas e.g. CentOS 5, RHEL 5. When running programs on
newer glibc these applications may exhibit high contention when
accessing arenas. In these cases it may be beneficial to increase
M_ARENA_MAX to match the number of threads. This is similar in behaviour
to strategies taken by tcmalloc and jemalloc e.g. per-thread allocation
pools.
.TP
.BR M_ARENA_TEST
is the limit, in number of arenas created, at which the system
configuration will be examined to evaluate a hard limit on the
number of created arenas. The computed limit is implementation
defined and usually a multiple of the number of available cores.
Once the limit is computed the result is final and constrains
the total number of arenas.
See M_ARENA_MAX for the definition of an arena.
This parameter has been available since glibc 2.10 via
--enable-experimental-malloc, or glibc 2.15 by default.
.TP
.BR M_CHECK_ACTION
Setting this parameter controls how glibc responds when various kinds
of programming errors are detected (e.g., freeing the same pointer twice).
@ -286,22 +316,7 @@ is a trade-off between increasing the number of system calls
(when the parameter is set low)
and wasting unused memory at the top of the heap
(when the parameter is set high).
.\" FIXME Do the arena parameters need to be documented?
.\" .TP
.\" .BR M_ARENA_TEST " (since glibc 2.10)"
.\" .TP
.\" .BR M_ARENA_MAX " (since glibc 2.10)"
.\"
.\" Environment variables
.\" MALLOC_ARENA_MAX_
.\" MALLOC_ARENA_TEST_
.\"
.\" http://udrepper.livejournal.com/20948.html describes some details
.\" of the MALLOC_ARENA_* environment variables.
.\"
.\" These macros aren't enabled in production releases until 2.15?
.\" (see glibc malloc/Makefile)
.\"
.SS Environment variables
A number of environment variables can be defined
to modify some of the same parameters as are controlled by
@ -319,7 +334,17 @@ For security reasons,
these variables are ignored in set-user-ID and set-group-ID programs.
The environment variables are as follows
(note the trailing underscore at the end of the name of each variable):
(note the trailing underscore at the end of the name of some variables):
.TP
.BR MALLOC_ARENA_MAX
Controls the same parameter as
.BR mallopt ()
.BR M_ARENA_MAX .
.TP
.BR MALLOC_ARENA_TEST
Controls the same parameter as
.BR mallopt ()
.BR M_ARENA_TEST .
.TP
.BR MALLOC_CHECK_
This environment variable controls the same parameter as