Red Hat Bugzilla – Bug 803565
malloc tuning parameters and informational capabilities not documented
Last modified: 2015-09-27 22:22:31 EDT
Description of problem:
mallopt and its associated environment variables to tune glibc's malloc behaviour are not documented.
Should be enough to get the process started.
I tend to think this should be part of our developer guide rather than a man page.
Version-Release number of selected component (if applicable):
Steps to Reproduce:
Well, you need to understand this was opened at the request of Fujitsu and they have taken the position that if we have not documented something then it is not supported.
Our RHEL distribution doesn't include any documention WRT mallopt. Thus user's can not look up this stuff in a man page -- they have to go to google or some other search engine.
In simplest terms, mallopt is a library call that allows a program to change the behaviour of the malloc memory allocator. So for example, the allocator has heuristics to determine long vs short lived objects. The former it tries to allocate via mmap and the latter via sbrk. However, a programmer who knows their application may choose to override the heuristics by setting M_MMAP_THRESHOLD.
Or another example, in multi-threaded applications, the allocator will create multiple "arenas" in response to lock contention in existing arenas. This can improve the performance significantly for some multi-threaded applications. However, this can cause an increase in memory usage and developers may want to limit the number of arena's that can be created. They can do so using the mallopt interface. For example, if they want no more than 8 arenas to be created, they can issue the following library call:
mallopt (M_ARENA_MAX, 8);
mallopt's first argument can be:
M_MXFAST, M_TRIM_THRESHOLD, M_TOP_PAD, M_MMAP_THRESHOLD, M_MMAP_MAX, M_CHECK_ACTION, M_PERTURB, M_ARENA_TEST or M_ARENA_MAX. Hopefully most of those are defined on the pages I referenced. I can provide additional information for any which aren't referenced.
malloc_trim is a library call which requests that the allocator return any unused memory back to the OS. This normally happens automatically when an object is freed, but in some cases when free-ing small objects glibc might not immediately release the memory back to the OS in the hope that it can use the free memory to satisfy upcoming memory allocation requests. (it is expensive to allocate from and release memory back to the OS).
malloc_stats can be used to dump information about the allocator's internal state to stderr. mallinfo is similar, but instead places the state into a structure.
Verified the inclusion of additional section, noted one typo:
An allocator has heuristics to determine long versus short lived objects. For the former, it attempts to allocate with mmap. For the later, it attempts to allocate with sbrk.
[comment] Also Jeff can you check the text, are you satisfied with additional text?
"An allocator has heuristics" "For example, the allocator has heuristics.
In the paragraph about creating multiple arenas, it's probably worth mentioning that the allocator has limits on the number of arenas to create. For 32bit targets it'll create 2 * # cores arenas, for a 64 bit target, it'll create 8 * # cores arenas. mallopt allows the developer to override those limits.
In malloc_stats. You probably want some whitespace between "strerror.mallinfo" otherwise it looks like one long sentence where mallinfo as a field in the strerror structure rather than two distinct sentences describing two related functions (malloc_stats and mallinfo).