1 files changed, 95 insertions, 36 deletions

diff --git a/lib/libc/stdlib/malloc.3 b/lib/libc/stdlib/malloc.3
index 4667588a369c..580b19a426b4 100644
--- a/lib/libc/stdlib/malloc.3
+++ b/lib/libc/stdlib/malloc.3
@@ -32,7 +32,7 @@
 .\"     @(#)malloc.3	8.1 (Berkeley) 6/4/93
 .\" $FreeBSD$
 .\"
-.Dd June 15, 2007
+.Dd February 17, 2008
 .Dt MALLOC 3
 .Os
 .Sh NAME
@@ -95,7 +95,7 @@ bytes.
 The contents of the memory are unchanged up to the lesser of the new and
 old sizes.
 If the new size is larger,
-the value of the newly allocated portion of the memory is undefined.
+the contents of the newly allocated portion of the memory are undefined.
 Upon success, the memory referenced by
 .Fa ptr
 is freed and a pointer to the newly allocated memory is returned.
@@ -165,11 +165,18 @@ the value of the environment variable
 .Ev MALLOC_OPTIONS ,
 and the string pointed to by the global variable
 .Va _malloc_options
-will be interpreted, in that order, character by character as flags.
+will be interpreted, in that order, from left to right as flags.
 .Pp
-Most flags are single letters,
-where uppercase indicates that the behavior is set, or on,
-and lowercase means that the behavior is not set, or off.
+Each flag is a single letter, optionally prefixed by a non-negative base 10
+integer repetition count.
+For example,
+.Dq 3N
+is equivalent to
+.Dq NNN .
+Some flags control parameter magnitudes, where uppercase increases the
+magnitude, and lowercase decreases the magnitude.
+Other flags control boolean parameters, where uppercase indicates that a
+behavior is set, or on, and lowercase means that a behavior is not set, or off.
 .Bl -tag -width indent
 .It A
 All warnings (except for the warning about unknown
@@ -177,15 +184,46 @@ flags being set) become fatal.
 The process will call
 .Xr abort 3
 in these cases.
-.It H
+.It B
+Double/halve the per-arena lock contention threshold at which a thread is
+randomly re-assigned to an arena.
+This dynamic load balancing tends to push threads away from highly contended
+arenas, which avoids worst case contention scenarios in which threads
+disproportionately utilize arenas.
+However, due to the highly dynamic load that applications may place on the
+allocator, it is impossible for the allocator to know in advance how sensitive
+it should be to contention over arenas.
+Therefore, some applications may benefit from increasing or decreasing this
+threshold parameter.
+This option is not available for some configurations (non-PIC).
+.It D
 Use
-.Xr madvise 2
-when pages within a chunk are no longer in use, but the chunk as a whole cannot
-yet be deallocated.
-This is primarily of use when swapping is a real possibility, due to the high
-overhead of the
-.Fn madvise
-system call.
+.Xr sbrk 2
+to acquire memory in the data storage segment (DSS).
+This option is enabled by default.
+See the
+.Dq M
+option for related information and interactions.
+.It F
+Double/halve the per-arena maximum number of dirty unused pages that are
+allowed to accumulate before informing the kernel about at least half of those
+pages via
+.Xr madvise 2 .
+This provides the kernel with sufficient information to recycle dirty pages if
+physical memory becomes scarce and the pages remain unused.
+The default is 512 pages per arena;
+.Ev MALLOC_OPTIONS=10f
+will prevent any dirty unused pages from accumulating.
+.It H
+Obsoleted by the
+.Dq F
+option.
+.Ev MALLOC_OPTIONS=H
+sets the per-arena maximum number of dirty unused pages to 0, and
+.Ev MALLOC_OPTIONS=h
+resets the per-arena maximum number of dirty unused pages to the default.
+This option will be removed in
+.Fx 8.0 .
 .It J
 Each byte of new memory allocated by
 .Fn malloc ,
@@ -201,14 +239,27 @@ or
 will be initialized to 0x5a.
 This is intended for debugging and will impact performance negatively.
 .It K
-Increase/decrease the virtual memory chunk size by a factor of two.
+Double/halve the virtual memory chunk size.
 The default chunk size is 1 MB.
-This option can be specified multiple times.
+.It M
+Use
+.Xr mmap 2
+to acquire anonymously mapped memory.
+This option is enabled by default.
+If both the
+.Dq D
+and
+.Dq M
+options are enabled, the allocator prefers the DSS over anonymous mappings,
+but allocation only fails if memory cannot be acquired via either method.
+If neither option is enabled, then the
+.Dq M
+option is implicitly enabled in order to assure that there is a method for
+acquiring memory.
 .It N
-Increase/decrease the number of arenas by a factor of two.
+Double/halve the number of arenas.
 The default number of arenas is four times the number of CPUs, or one if there
 is a single CPU.
-This option can be specified multiple times.
 .It P
 Various statistics are printed at program exit via an
 .Xr atexit 3
@@ -218,16 +269,14 @@ while one or more threads are executing in the memory allocation functions.
 Therefore, this option should only be used with care; it is primarily intended
 as a performance tuning aid during application development.
 .It Q
-Increase/decrease the size of the allocation quantum by a factor of two.
+Double/halve the size of the allocation quantum.
 The default quantum is the minimum allowed by the architecture (typically 8 or
 16 bytes).
-This option can be specified multiple times.
 .It S
-Increase/decrease the size of the maximum size class that is a multiple of the
-quantum by a factor of two.
+Double/halve the size of the maximum size class that is a multiple of the
+quantum.
 Above this size, power-of-two spacing is used for size classes.
 The default value is 512 bytes.
-This option can be specified multiple times.
 .It U
 Generate
 .Dq utrace
@@ -283,18 +332,27 @@ is flawed.
 .Sh IMPLEMENTATION NOTES
 Traditionally, allocators have used
 .Xr sbrk 2
-to obtain memory, but this implementation uses
-.Xr mmap 2 ,
-and only uses
+to obtain memory, which is suboptimal for several reasons, including race
+conditions, increased fragmentation, and artificial limitations on maximum
+usable memory.
+This allocator uses both
 .Xr sbrk 2
-under limited circumstances, and only for 32-bit architectures.
-As a result, the
+and
+.Xr mmap 2
+by default, but it can be configured at run time to use only one or the other.
+If resource limits are not a primary concern, the preferred configuration is
+.Ev MALLOC_OPTIONS=dM
+or
+.Ev MALLOC_OPTIONS=DM .
+When so configured, the
 .Ar datasize
-resource limit has little practical effect for typical applications.
-The
+resource limit has little practical effect for typical applications; use
+.Ev MALLOC_OPTIONS=Dm
+if that is a concern.
+Regardless of allocator configuration, the
 .Ar vmemoryuse
-resource limit, however, can be used to bound the total virtual memory used by
-a process, as described in
+resource limit can be used to bound the total virtual memory used by a
+process, as described in
 .Xr limits 1 .
 .Pp
 This allocator uses multiple arenas in order to reduce lock contention for
@@ -326,11 +384,12 @@ separately in a single data structure that is shared by all threads.
 Huge objects are used by applications infrequently enough that this single
 data structure is not a scalability issue.
 .Pp
-Each chunk that is managed by an arena tracks its contents in a page map as
-runs of contiguous pages (unused, backing a set of small objects, or backing
-one large object).
+Each chunk that is managed by an arena tracks its contents as runs of
+contiguous pages (unused, backing a set of small objects, or backing one large
+object).
 The combination of chunk alignment and chunk page maps makes it possible to
-determine all metadata regarding small and large allocations in constant time.
+determine all metadata regarding small and large allocations in
+constant and logarithmic time, respectively.
 .Pp
 Small objects are managed in groups by page runs.
 Each run maintains a bitmap that tracks which regions are in use.