mallopt.3: Document M_ARENA_TEST, and M_ARENA_MAX.

  Hi Carlos,

On 08/24/2015 09:05 AM, Carlos O'Donell wrote:
> 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.

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
  

On 08/30/2015 08:06 AM, Michael Kerrisk (man-pages) wrote:
> diff --git a/man3/mallopt.3 b/man3/mallopt.3
> index c09e801..fd41bf0 100644
> --- a/man3/mallopt.3
> +++ b/man3/mallopt.3
> @@ -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.

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

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

On 31 August 2015 at 15:20, Carlos O'Donell <carlos@redhat.com> wrote:
> On 08/30/2015 08:06 AM, Michael Kerrisk (man-pages) wrote:
>> diff --git a/man3/mallopt.3 b/man3/mallopt.3
>> index c09e801..fd41bf0 100644
>> --- a/man3/mallopt.3
>> +++ b/man3/mallopt.3
>> @@ -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.
>
>>  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.
>
>>  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