mallopt.3: Document M_ARENA_TEST, and M_ARENA_MAX.

PATCH In review Carlos O'Donell 2 participants 4 messages Aug 24, 2015 – Sep 1, 2015 3 messages not in the archive Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore

Share & tools

lore

Carlos O'Donell

author

2015-08-24 16:05 UTC #0 lore raw

PATCH 1/1 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 behaviour 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 man page along with their environment variables.

Tested with glibc master on x86_64 to verify it works as expected. Tested patch with linux man pages master.
Please apply.

Signed-off-by Carlos O'Donell <[email protected]>

man3/mallopt.3 +42 ~~-17~~

index cb3da4c..53d17a0 100644
@@ -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

---

Cheers,
Carlos.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): [email protected]

Michael Kerrisk (man-pages)

2015-08-30 12:06 UTC #2 lore raw

Hi Carlos,

Quoted 22 lines · Carlos O'Donell

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 behaviour 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.

Quoted 6 lines

This change describes these two options in the mallopt man page along with their environment variables.
Tested with glibc master on x86_64 to verify it works as expected. Tested patch with linux man pages master.
Please apply.

Applied. I made a number of small wording fix-uos, and put a couple that I thought might be worth double checking in commitb72bd8d. Could you take a look at that commit please (also pasted as a patch at the foot of this mail).

Cheers,

Michael

man3/mallopt.3 +3 -3

index c09e801..fd41bf0 100644
@@ -66,8 +66,8 @@ and since 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 versions,
-these applications may exhibit high contention when accessing arenas.
+When employing newer glibc versions, applications may in
+some cases exhibit high contention when accessing arenas.
 In these cases, it may be beneficial to increase
 .B M_ARENA_MAX
 to match the number of threads.

@@ -79,7 +79,7 @@ This 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 is usually a multiple of the number of available cores.
+and is usually a multiple of the number of available CPUs.
 Once the limit is computed, the result is final and constrains
 the total number of arenas.
 See

Signature · 7 lines

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): [email protected]

Carlos O'Donell

author

2015-08-31 13:20 UTC #4 lore raw

man3/mallopt.3 and since glibc 2.15 by default. · line 70

Quoted 12 lines · Michael Kerrisk (man-pages)

man3/mallopt.3 +2 -2

index c09e801..fd41bf0 100644
@@ -66,8 +66,8 @@ and since 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 versions,
-these applications may exhibit high contention when accessing arenas.
+When employing newer glibc versions, applications may in
+some cases exhibit high contention when accessing arenas.

OK.

man3/mallopt.3 This is the limit, in number of arenas created, at which the system · line 82

Quoted 9 lines

man3/mallopt.3 +1 -1

 In these cases, it may be beneficial to increase
 .B M_ARENA_MAX
 to match the number of threads.

@@ -79,7 +79,7 @@ This 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 is usually a multiple of the number of available cores.
+and is usually a multiple of the number of available CPUs.

I like this. This is better than what I wrote, since a core is not the right unit here, we are reading /sys/devices/system/cpu/online, or /proc/stat or /proc/cpuinfo to compute the number of online cpus.

man3/mallopt.3 This is the limit, in number of arenas created, at which the system · line 85

Quoted 3 lines

man3/mallopt.3 +0 -0

 Once the limit is computed, the result is final and constrains
 the total number of arenas.
 See

Thanks for the commit and fixup!

Cheers,
Carlos.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): [email protected]

Michael Kerrisk (man-pages)

2015-09-01 13:35 UTC #6 lore raw

Quoted 30 lines · Carlos O'Donell

man3/mallopt.3 and since glibc 2.15 by default. · line 70
Quoted 12 lines · Michael Kerrisk (man-pages)
man3/mallopt.3 +2 -2
index c09e801..fd41bf0 100644
@@ -66,8 +66,8 @@ and since 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 versions,
-these applications may exhibit high contention when accessing arenas.
+When employing newer glibc versions, applications may in
+some cases exhibit high contention when accessing arenas.
OK.
man3/mallopt.3 This is the limit, in number of arenas created, at which the system · line 82
Quoted 9 lines
man3/mallopt.3 +1 -1
 In these cases, it may be beneficial to increase
 .B M_ARENA_MAX
 to match the number of threads.
@@ -79,7 +79,7 @@ This 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 is usually a multiple of the number of available cores.
+and is usually a multiple of the number of available CPUs.
I like this. This is better than what I wrote, since a core is not the right unit here, we are reading /sys/devices/system/cpu/online, or /proc/stat or /proc/cpuinfo to compute the number of online cpus.

Quoted 5 lines

man3/mallopt.3 This is the limit, in number of arenas created, at which the system · line 85
Quoted 3 lines
man3/mallopt.3 +0 -0
 Once the limit is computed, the result is final and constrains
 the total number of arenas.
 See
Thanks for the commit and fixup!

Thanks for checking the changes, Carlos!

Cheers,

Michael

Signature · 7 lines

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html