Bug 803565

Summary: malloc tuning parameters and informational capabilities not documented
Product: Red Hat Enterprise Linux 6 Reporter: Jeff Law <law>
Component: doc-Developer_GuideAssignee: Jacquelynn East <jeast>
Status: CLOSED CURRENTRELEASE QA Contact: ecs-bugs
Severity: unspecified Docs Contact:
Priority: unspecified    
Version: 6.2CC: jskeoch, rlandman
Target Milestone: rcKeywords: Documentation
Target Release: ---   
Hardware: Unspecified   
OS: Unspecified   
Whiteboard:
Fixed In Version: Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
: 854080 (view as bug list) Environment:
Last Closed: 2013-02-26 05:04:58 UTC Type: ---
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:
Embargoed:
Bug Depends On:    
Bug Blocks: 854080    
Deadline: 2012-09-17   

Description Jeff Law 2012-03-15 03:59:57 UTC
Description of problem:
mallopt and its associated environment variables to tune glibc's malloc behaviour are not documented.

http://www.makelinux.net/man/3/M/mallopt
http://www.gnu.org/software/libc/manual/html_node/Malloc-Tunable-Parameters.html

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):
All

How reproducible:


Steps to Reproduce:
1.
2.
3.
  
Actual results:


Expected results:


Additional info:

Comment 4 Jeff Law 2012-08-27 17:29:22 UTC
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.

Comment 6 John Skeoch 2012-10-03 01:38:10 UTC
Verified the inclusion of additional section, noted one typo:

http://documentation-devel.engineering.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/6/html/Developer_Guide/appendix.html

Red_Hat_Enterprise_Linux-Developer_Guide-6-en-US-2-17

---

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. 

[typo] s/later/latter 

[comment] Also Jeff can you check the text, are you satisfied with additional text?

Comment 8 Jeff Law 2012-10-03 19:23:18 UTC
"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).