1452 lines
55 KiB
Groff
1452 lines
55 KiB
Groff
.\" Copyright (c) 2006-2010 Jason Evans <jasone@canonware.com>.
|
|
.\" All rights reserved.
|
|
.\" Copyright (c) 2009 Facebook, Inc. All rights reserved.
|
|
.\"
|
|
.\" See COPYING for licensing terms provided by the above copyright holders.
|
|
.\"
|
|
.\" Copyright (c) 1980, 1991, 1993
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to Berkeley by
|
|
.\" the American National Standards Committee X3, on Information
|
|
.\" Processing Systems.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" @(#)malloc.3 8.1 (Berkeley) 6/4/93
|
|
.\" $FreeBSD: head/lib/libc/stdlib/malloc.3 182225 2008-08-27 02:00:53Z jasone $
|
|
.\"
|
|
.Dd February 11, 2010
|
|
.Dt JEMALLOC 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm @jemalloc_prefix@malloc ,
|
|
.Nm @jemalloc_prefix@calloc ,
|
|
.Nm @jemalloc_prefix@posix_memalign ,
|
|
.Nm @jemalloc_prefix@realloc ,
|
|
.Nm @jemalloc_prefix@free ,
|
|
.Nm @jemalloc_prefix@malloc_usable_size ,
|
|
.Nm @jemalloc_prefix@malloc_stats_print ,
|
|
.Nm @jemalloc_prefix@mallctl ,
|
|
.Nm @jemalloc_prefix@mallctlnametomib ,
|
|
.Nm @jemalloc_prefix@mallctlbymib
|
|
.Nd general purpose memory allocation functions
|
|
.Sh LIBRARY
|
|
.Sy libjemalloc@install_suffix@
|
|
.Sh SYNOPSIS
|
|
.In stdlib.h
|
|
.In jemalloc/jemalloc@install_suffix@.h
|
|
.Ft void *
|
|
.Fn @jemalloc_prefix@malloc "size_t size"
|
|
.Ft void *
|
|
.Fn @jemalloc_prefix@calloc "size_t number" "size_t size"
|
|
.Ft int
|
|
.Fn @jemalloc_prefix@posix_memalign "void **ptr" "size_t alignment" "size_t size"
|
|
.Ft void *
|
|
.Fn @jemalloc_prefix@realloc "void *ptr" "size_t size"
|
|
.Ft void
|
|
.Fn @jemalloc_prefix@free "void *ptr"
|
|
.Ft size_t
|
|
.Fn @jemalloc_prefix@malloc_usable_size "const void *ptr"
|
|
.Ft void
|
|
.Fn @jemalloc_prefix@malloc_stats_print "void (*write4)(void *" "const char *" "const char *" "const char *" "const char *)" "const char *opts"
|
|
.Ft int
|
|
.Fn @jemalloc_prefix@mallctl "const char *name" "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen"
|
|
.Ft int
|
|
.Fn @jemalloc_prefix@mallctlnametomib "const char *name" "int *mibp" "size_t *miblenp"
|
|
.Ft int
|
|
.Fn @jemalloc_prefix@mallctlbymib "const size_t *mib" "size_t miblen" "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen"
|
|
.Ft const char *
|
|
.Va @jemalloc_prefix@malloc_options ;
|
|
.Ft void
|
|
.Fn \*(lp*@jemalloc_prefix@malloc_message\*(rp "void *w4opaque" "const char *p1" "const char *p2" "const char *p3" "const char *p4"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn @jemalloc_prefix@malloc
|
|
function allocates
|
|
.Fa size
|
|
bytes of uninitialized memory.
|
|
The allocated space is suitably aligned
|
|
@roff_tiny@(after possible pointer coercion)
|
|
for storage of any type of object.
|
|
.Pp
|
|
The
|
|
.Fn @jemalloc_prefix@calloc
|
|
function allocates space for
|
|
.Fa number
|
|
objects,
|
|
each
|
|
.Fa size
|
|
bytes in length.
|
|
The result is identical to calling
|
|
.Fn @jemalloc_prefix@malloc
|
|
with an argument of
|
|
.Dq "number * size" ,
|
|
with the exception that the allocated memory is explicitly initialized
|
|
to zero bytes.
|
|
.Pp
|
|
The
|
|
.Fn @jemalloc_prefix@posix_memalign
|
|
function allocates
|
|
.Fa size
|
|
bytes of memory such that the allocation's base address is an even multiple of
|
|
.Fa alignment ,
|
|
and returns the allocation in the value pointed to by
|
|
.Fa ptr .
|
|
The requested
|
|
.Fa alignment
|
|
must be a power of 2 at least as large as
|
|
.Fn sizeof "void *" .
|
|
.Pp
|
|
The
|
|
.Fn @jemalloc_prefix@realloc
|
|
function changes the size of the previously allocated memory referenced by
|
|
.Fa ptr
|
|
to
|
|
.Fa size
|
|
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 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.
|
|
Note that
|
|
.Fn @jemalloc_prefix@realloc
|
|
may move the memory allocation, resulting in a different return value than
|
|
.Fa ptr .
|
|
If
|
|
.Fa ptr
|
|
is
|
|
.Dv NULL ,
|
|
the
|
|
.Fn @jemalloc_prefix@realloc
|
|
function behaves identically to
|
|
.Fn @jemalloc_prefix@malloc
|
|
for the specified size.
|
|
.Pp
|
|
The
|
|
.Fn @jemalloc_prefix@free
|
|
function causes the allocated memory referenced by
|
|
.Fa ptr
|
|
to be made available for future allocations.
|
|
If
|
|
.Fa ptr
|
|
is
|
|
.Dv NULL ,
|
|
no action occurs.
|
|
.Pp
|
|
The
|
|
.Fn @jemalloc_prefix@malloc_usable_size
|
|
function returns the usable size of the allocation pointed to by
|
|
.Fa ptr .
|
|
The return value may be larger than the size that was requested during
|
|
allocation.
|
|
The
|
|
.Fn @jemalloc_prefix@malloc_usable_size
|
|
function is not a mechanism for in-place
|
|
.Fn @jemalloc_prefix@realloc ;
|
|
rather it is provided solely as a tool for introspection purposes.
|
|
Any discrepancy between the requested allocation size and the size reported by
|
|
.Fn @jemalloc_prefix@malloc_usable_size
|
|
should not be depended on, since such behavior is entirely
|
|
implementation-dependent.
|
|
.Pp
|
|
The
|
|
.Fn @jemalloc_prefix@malloc_stats_print
|
|
function writes human-readable summary statistics via the
|
|
.Fa write4
|
|
callback function pointer and
|
|
.Fa w4opaque
|
|
data passed to
|
|
.Fn write4 ,
|
|
or
|
|
.Fn @jemalloc_prefix@malloc_message
|
|
if
|
|
.Fa write4
|
|
is
|
|
.Dv NULL .
|
|
This function can be called repeatedly.
|
|
General information that never changes
|
|
during execution can be omitted by specifying
|
|
.Dq g
|
|
as a character within the
|
|
.Fa opts
|
|
string.
|
|
Note that
|
|
.Fn @jemalloc_prefix@malloc_message
|
|
uses the
|
|
.Fn @jemalloc_prefix@mallctl*
|
|
functions internally, so inconsistent statistics can be reported if multiple
|
|
threads use these functions simultaneously.
|
|
@roff_stats@.Dq m
|
|
@roff_stats@and
|
|
@roff_stats@.Dq a
|
|
@roff_stats@can be specified to omit merged arena and per arena statistics,
|
|
@roff_stats@respectively.
|
|
@roff_stats@.Dq b
|
|
@roff_stats@and
|
|
@roff_stats@.Dq l
|
|
@roff_stats@can be specified to omit per size class statistics for bins and
|
|
@roff_stats@large objects, respectively.
|
|
Unrecognized characters are silently ignored.
|
|
@roff_tcache@Note that thread caching may prevent some statistics from being
|
|
@roff_tcache@completely up to date, since extra locking would be required to
|
|
@roff_tcache@merge counters that track thread cache operations.
|
|
.Pp
|
|
The
|
|
.Fn @jemalloc_prefix@mallctl
|
|
function provides a general interface for introspecting the memory allocator,
|
|
as well as setting modifiable parameters and triggering actions.
|
|
The period-separated
|
|
.Fa name
|
|
argument specifies a location in a tree-structured namespace; see the
|
|
.Sx "MALLCTL NAMESPACE"
|
|
section for documentation on the tree contents.
|
|
To read a value, pass a pointer via
|
|
.Fa oldp
|
|
to adequate space to contain the value, and a pointer to its length via
|
|
.Fa oldlenp ;
|
|
otherwise pass
|
|
.Dv NULL
|
|
and
|
|
.Dv NULL .
|
|
Similarly, to write a value, pass a pointer to the value via
|
|
.Fa newp ,
|
|
and its length via
|
|
.Fa newlen ;
|
|
otherwise pass
|
|
.Dv NULL
|
|
and 0.
|
|
.Pp
|
|
The
|
|
.Fn @jemalloc_prefix@mallctlnametomib
|
|
function provides a way to avoid repeated name lookups for applications that
|
|
repeatedly query the same portion of the namespace, by translating a name to a
|
|
.Dq Management Information Base
|
|
(MIB) that can be passed repeatedly to
|
|
.Fn @jemalloc_prefix@mallctlbymib .
|
|
Upon successful return from
|
|
.Fn @jemalloc_prefix@mallctlnametomib ,
|
|
.Fa mibp
|
|
contains an array of
|
|
.Fa *miblenp
|
|
integers, where
|
|
.Fa *miblenp
|
|
is the lesser of the number of components in
|
|
.Fa name
|
|
and the input value of
|
|
.Fa *miblenp .
|
|
Thus it is possible to pass a
|
|
.Fa *miblenp
|
|
that is smaller than the number of period-separated name components, which
|
|
results in a partial MIB that can be used as the basis for constructing a
|
|
complete MIB.
|
|
For name components that are integers (e.g. the 2 in
|
|
.Qq arenas.bin.2.size ) ,
|
|
the corresponding MIB component will always be that integer.
|
|
Therefore, it is legitimate to construct code like the following:
|
|
.Pp
|
|
.Bd -literal -offset indent -compact
|
|
unsigned nbins, i;
|
|
int mib[4];
|
|
size_t len, miblen;
|
|
|
|
len = sizeof(nbins);
|
|
@jemalloc_prefix@mallctl("arenas.nbins", &nbins, &len, NULL, 0);
|
|
|
|
miblen = 4;
|
|
@jemalloc_prefix@mallnametomib("arenas.bin.0.size", mib, &miblen);
|
|
for (i = 0; i < nbins; i++) {
|
|
size_t bin_size;
|
|
|
|
mib[2] = i;
|
|
len = sizeof(bin_size);
|
|
@jemalloc_prefix@mallctlbymib(mib, miblen, &bin_size, &len, NULL, 0);
|
|
/* Do something with bin_size... */
|
|
}
|
|
.Ed
|
|
.Sh TUNING
|
|
Once, when the first call is made to one of these memory allocation
|
|
routines, various flags will be set or reset, which affects the
|
|
workings of this allocator implementation.
|
|
.Pp
|
|
The
|
|
.Dq name
|
|
of the file referenced by the symbolic link named
|
|
.Pa /etc/jemalloc.conf ,
|
|
the value of the environment variable
|
|
.Ev JEMALLOC_OPTIONS ,
|
|
and the string pointed to by the global variable
|
|
.Va @jemalloc_prefix@malloc_options
|
|
will be interpreted, in that order, from left to right as flags.
|
|
.Pp
|
|
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
|
|
flags being set) become fatal.
|
|
The process will call
|
|
.Xr abort 3
|
|
in these cases.
|
|
@roff_prof@.It B
|
|
@roff_prof@Double/halve the maximum backtrace depth when profiling memory
|
|
@roff_prof@allocation activity.
|
|
@roff_prof@The default is 4.
|
|
.It C
|
|
Double/halve the size of the maximum size class that is a multiple of the
|
|
cacheline size (64).
|
|
Above this size, subpage spacing (256 bytes) is used for size classes.
|
|
The default value is 512 bytes.
|
|
.It D
|
|
Halve/double the per-arena minimum ratio of active to dirty pages.
|
|
Some dirty unused pages may be allowed to accumulate, within the limit set by
|
|
the ratio, 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 minimum ratio is 32:1;
|
|
.Ev JEMALLOC_OPTIONS=6D
|
|
will disable dirty page purging.
|
|
@roff_prof@.It F
|
|
@roff_prof@Profile memory allocation activity, and use an
|
|
@roff_prof@.Xr atexit 3
|
|
@roff_prof@function to dump final memory usage to a file named according to
|
|
@roff_prof@the pattern
|
|
@roff_prof@.Pa <prefix>.<pid>.<seq>.f.heap ,
|
|
@roff_prof@where
|
|
@roff_prof@.Pa <prefix>
|
|
@roff_prof@is controlled by the
|
|
@roff_prof@JEMALLOC_PROF_PREFIX
|
|
@roff_prof@environment variable.
|
|
@roff_prof@See the
|
|
@roff_prof@.Dq B
|
|
@roff_prof@option for backtrace depth control.
|
|
@roff_prof@See the
|
|
@roff_prof@.Dq I
|
|
@roff_prof@option for information on interval-triggered profile dumping, and the
|
|
@roff_prof@.Dq U
|
|
@roff_prof@option for information on high-water-triggered profile dumping.
|
|
@roff_prof@Profile output is compatible with the pprof Perl script, which is
|
|
@roff_prof@part of the google-perftools package
|
|
@roff_prof@(http://code.google.com/p/google-perftools/).
|
|
@roff_tcache@.It G
|
|
@roff_tcache@Double/halve the approximate interval (counted in terms of
|
|
@roff_tcache@thread-specific cache allocation/deallocation events) between full
|
|
@roff_tcache@thread-specific cache garbage collection sweeps.
|
|
@roff_tcache@Garbage collection is actually performed incrementally, one size
|
|
@roff_tcache@class at a time, in order to avoid large collection pauses.
|
|
@roff_tcache@The default sweep interval is 8192;
|
|
@roff_tcache@.Ev JEMALLOC_OPTIONS=14g
|
|
@roff_tcache@will disable garbage collection.
|
|
@roff_tcache@.It H
|
|
@roff_tcache@Double/halve the number of thread-specific cache slots per size
|
|
@roff_tcache@class.
|
|
@roff_tcache@When there are multiple threads, each thread uses a
|
|
@roff_tcache@thread-specific cache for small and medium objects.
|
|
@roff_tcache@Thread-specific caching allows many allocations to be satisfied
|
|
@roff_tcache@without performing any thread synchronization, at the cost of
|
|
@roff_tcache@increased memory use.
|
|
@roff_tcache@See the
|
|
@roff_tcache@.Dq G
|
|
@roff_tcache@option for related tuning information.
|
|
@roff_tcache@The default number of cache slots is 128;
|
|
@roff_tcache@.Ev JEMALLOC_OPTIONS=7h
|
|
@roff_tcache@will disable thread-specific caching.
|
|
@roff_tcache@Note that one cache slot per size class is not a valid
|
|
@roff_tcache@configuration due to implementation details.
|
|
@roff_prof@.It I
|
|
@roff_prof@Double/halve the average interval between memory profile dumps, as
|
|
@roff_prof@measured in bytes of allocation activity.
|
|
@roff_prof@The actual interval between dumps may be sporadic because
|
|
@roff_prof@decentralized allocation counters are used to avoid synchronization
|
|
@roff_prof@bottlenecks.
|
|
@roff_prof@Profiles are dumped to files named according to the pattern
|
|
@roff_prof@.Pa <prefix>.<pid>.<seq>.i<iseq>.heap ,
|
|
@roff_prof@where
|
|
@roff_prof@.Pa <prefix>
|
|
@roff_prof@is controlled by the
|
|
@roff_prof@JEMALLOC_PROF_PREFIX
|
|
@roff_prof@environment variable.
|
|
@roff_prof@The default average interval is 1 GiB.
|
|
@roff_fill@.It J
|
|
@roff_fill@Each byte of new memory allocated by
|
|
@roff_fill@.Fn @jemalloc_prefix@malloc
|
|
@roff_fill@or
|
|
@roff_fill@.Fn @jemalloc_prefix@realloc
|
|
@roff_fill@will be initialized to 0xa5.
|
|
@roff_fill@All memory returned by
|
|
@roff_fill@.Fn @jemalloc_prefix@free
|
|
@roff_fill@or
|
|
@roff_fill@.Fn @jemalloc_prefix@realloc
|
|
@roff_fill@will be initialized to 0x5a.
|
|
@roff_fill@This is intended for debugging and will impact performance
|
|
@roff_fill@negatively.
|
|
.It K
|
|
Double/halve the virtual memory chunk size.
|
|
The default chunk size is 4 MiB.
|
|
@roff_prof@.It L
|
|
@roff_prof@Use an
|
|
@roff_prof@.Xr atexit 3
|
|
@roff_prof@function to report memory leaks.
|
|
@roff_prof@See the
|
|
@roff_prof@.Dq B
|
|
@roff_prof@option for backtrace depth control.
|
|
@roff_prof@See the
|
|
@roff_prof@.Dq F option for information on analyzing heap profile output.
|
|
@roff_prof@This option is disabled by default.
|
|
.It M
|
|
Double/halve the size of the maximum medium size class.
|
|
The valid range is from one page to one half chunk.
|
|
The default value is 32 KiB.
|
|
.It N
|
|
Double/halve the number of arenas.
|
|
The default number of arenas is
|
|
@roff_tcache@two
|
|
@roff_no_tcache@four
|
|
times the number of CPUs, or one if there is a single CPU.
|
|
@roff_swap@.It O
|
|
@roff_swap@Over-commit memory as a side effect of using anonymous
|
|
@roff_swap@.Xr mmap 2
|
|
@roff_swap@@roff_dss@ and
|
|
@roff_swap@@roff_dss@.Xr sbrk 2
|
|
@roff_swap@for virtual memory allocation.
|
|
@roff_swap@In order for overcommit to be disabled, the
|
|
@roff_swap@.Dq swap.fds
|
|
@roff_swap@mallctl must have been successfully written to.
|
|
@roff_swap@This option is enabled by default.
|
|
.It P
|
|
The
|
|
.Fn malloc_stats_print
|
|
function is called at program exit via an
|
|
.Xr atexit 3
|
|
function.
|
|
@roff_stats@This has the potential to cause deadlock for a multi-threaded
|
|
@roff_stats@process that exits while one or more threads are executing in the
|
|
@roff_stats@memory allocation functions.
|
|
@roff_stats@Therefore, this option should only be used with care; it is
|
|
@roff_stats@primarily intended as a performance tuning aid during application
|
|
@roff_stats@development.
|
|
.It Q
|
|
Double/halve the size of the maximum size class that is a multiple of the
|
|
quantum (8 or 16 bytes, depending on architecture).
|
|
Above this size, cacheline spacing is used for size classes.
|
|
The default value is 128 bytes.
|
|
@roff_prof@.It U
|
|
@roff_prof@Trigger a memory profile dump every time the total virtual memory
|
|
@roff_prof@exceeds the previous maximum.
|
|
@roff_prof@Profiles are dumped to files named according to the pattern
|
|
@roff_prof@.Pa <prefix>.<pid>.<seq>.u<useq>.heap ,
|
|
@roff_prof@where
|
|
@roff_prof@.Pa <prefix>
|
|
@roff_prof@is controlled by the
|
|
@roff_prof@JEMALLOC_PROF_PREFIX
|
|
@roff_prof@environment variable.
|
|
@roff_prof@This option is disabled by default.
|
|
@roff_sysv@.It V
|
|
@roff_sysv@Attempting to allocate zero bytes will return a
|
|
@roff_sysv@.Dv NULL
|
|
@roff_sysv@pointer instead of a valid pointer.
|
|
@roff_sysv@(The default behavior is to make a minimal allocation and return a
|
|
@roff_sysv@pointer to it.)
|
|
@roff_sysv@This option is provided for System V compatibility.
|
|
@roff_sysv@@roff_xmalloc@This option is incompatible with the
|
|
@roff_sysv@@roff_xmalloc@.Dq X
|
|
@roff_sysv@@roff_xmalloc@option.
|
|
@roff_xmalloc@.It X
|
|
@roff_xmalloc@Rather than return failure for any allocation function, display a
|
|
@roff_xmalloc@diagnostic message on
|
|
@roff_xmalloc@.Dv STDERR_FILENO
|
|
@roff_xmalloc@and cause the program to drop core (using
|
|
@roff_xmalloc@.Xr abort 3 ) .
|
|
@roff_xmalloc@This option should be set at compile time by including the
|
|
@roff_xmalloc@following in the source code:
|
|
@roff_xmalloc@.Bd -literal -offset indent
|
|
@roff_xmalloc@@jemalloc_prefix@malloc_options = "X";
|
|
@roff_xmalloc@.Ed
|
|
@roff_fill@.It Z
|
|
@roff_fill@Each byte of new memory allocated by
|
|
@roff_fill@.Fn @jemalloc_prefix@malloc
|
|
@roff_fill@or
|
|
@roff_fill@.Fn @jemalloc_prefix@realloc
|
|
@roff_fill@will be initialized to 0.
|
|
@roff_fill@Note that this initialization only happens once for each byte, so
|
|
@roff_fill@.Fn @jemalloc_prefix@realloc
|
|
@roff_fill@calls do not zero memory that was previously allocated.
|
|
@roff_fill@This is intended for debugging and will impact performance
|
|
@roff_fill@negatively.
|
|
.El
|
|
.Pp
|
|
@roff_fill@The
|
|
@roff_fill@.Dq J
|
|
@roff_fill@and
|
|
@roff_fill@.Dq Z
|
|
@roff_fill@options are intended for testing and debugging.
|
|
@roff_fill@An application which changes its behavior when these options are used
|
|
@roff_fill@is flawed.
|
|
.Sh IMPLEMENTATION NOTES
|
|
@roff_dss@Traditionally, allocators have used
|
|
@roff_dss@.Xr sbrk 2
|
|
@roff_dss@to obtain memory, which is suboptimal for several reasons, including
|
|
@roff_dss@race conditions, increased fragmentation, and artificial limitations
|
|
@roff_dss@on maximum usable memory.
|
|
@roff_dss@This allocator uses both
|
|
@roff_dss@.Xr sbrk 2
|
|
@roff_dss@and
|
|
@roff_dss@.Xr mmap 2 ,
|
|
@roff_dss@in that order of preference.
|
|
.Pp
|
|
This allocator uses multiple arenas in order to reduce lock contention for
|
|
threaded programs on multi-processor systems.
|
|
This works well with regard to threading scalability, but incurs some costs.
|
|
There is a small fixed per-arena overhead, and additionally, arenas manage
|
|
memory completely independently of each other, which means a small fixed
|
|
increase in overall memory fragmentation.
|
|
These overheads are not generally an issue, given the number of arenas normally
|
|
used.
|
|
Note that using substantially more arenas than the default is not likely to
|
|
improve performance, mainly due to reduced cache performance.
|
|
However, it may make sense to reduce the number of arenas if an application
|
|
does not make much use of the allocation functions.
|
|
.Pp
|
|
@roff_tcache@In addition to multiple arenas, this allocator supports
|
|
@roff_tcache@thread-specific caching for small and medium objects, in order to
|
|
@roff_tcache@make it possible to completely avoid synchronization for most small
|
|
@roff_tcache@and medium allocation requests.
|
|
@roff_tcache@Such caching allows very fast allocation in the common case, but it
|
|
@roff_tcache@increases memory usage and fragmentation, since a bounded number of
|
|
@roff_tcache@objects can remain allocated in each thread cache.
|
|
@roff_tcache@.Pp
|
|
Memory is conceptually broken into equal-sized chunks, where the chunk size is
|
|
a power of two that is greater than the page size.
|
|
Chunks are always aligned to multiples of the chunk size.
|
|
This alignment makes it possible to find metadata for user objects very
|
|
quickly.
|
|
.Pp
|
|
User objects are broken into four categories according to size: small, medium,
|
|
large, and huge.
|
|
Small objects are smaller than one page.
|
|
Medium objects range from one page to an upper limit determined at run time (see
|
|
the
|
|
.Dq M
|
|
option).
|
|
Large objects are smaller than the chunk size.
|
|
Huge objects are a multiple of the chunk size.
|
|
Small, medium, and large objects are managed by arenas; huge objects are managed
|
|
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 as runs of
|
|
contiguous pages (unused, backing a set of small or medium 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.
|
|
.Pp
|
|
Small and medium objects are managed in groups by page runs.
|
|
Each run maintains a bitmap that tracks which regions are in use.
|
|
@roff_tiny@Allocation requests that are no more than half the quantum (8 or 16,
|
|
@roff_tiny@depending on architecture) are rounded up to the nearest power of
|
|
@roff_tiny@two.
|
|
Allocation requests that are
|
|
@roff_tiny@more than half the quantum, but
|
|
no more than the minimum cacheline-multiple size class (see the
|
|
.Dq Q
|
|
option) are rounded up to the nearest multiple of the
|
|
@roff_tiny@quantum.
|
|
@roff_no_tiny@quantum (8 or 16, depending on architecture).
|
|
Allocation requests that are more than the minimum cacheline-multiple size
|
|
class, but no more than the minimum subpage-multiple size class (see the
|
|
.Dq C
|
|
option) are rounded up to the nearest multiple of the cacheline size (64).
|
|
Allocation requests that are more than the minimum subpage-multiple size class,
|
|
but no more than the maximum subpage-multiple size class are rounded up to the
|
|
nearest multiple of the subpage size (256).
|
|
Allocation requests that are more than the maximum subpage-multiple size class,
|
|
but no more than the maximum medium size class (see the
|
|
.Dq M
|
|
option) are rounded up to the nearest medium size class; spacing is an
|
|
automatically determined power of two and ranges from the subpage size to the
|
|
page size.
|
|
Allocation requests that are more than the maximum medium size class, but small
|
|
enough to fit in an arena-managed chunk (see the
|
|
.Dq K
|
|
option), are rounded up to the nearest run size.
|
|
Allocation requests that are too large to fit in an arena-managed chunk are
|
|
rounded up to the nearest multiple of the chunk size.
|
|
.Pp
|
|
Allocations are packed tightly together, which can be an issue for
|
|
multi-threaded applications.
|
|
If you need to assure that allocations do not suffer from cacheline sharing,
|
|
round your allocation requests up to the nearest multiple of the cacheline
|
|
size.
|
|
.Sh MALLCTL NAMESPACE
|
|
The following names are defined in the namespace accessible via the
|
|
.Fn mallctl*
|
|
functions.
|
|
Value types are specified in parentheses, and their readable/writable statuses
|
|
are encoded as rw, r-, -w, or --.
|
|
A name element encoded as <i> or <j> indicates an integer component, where the
|
|
integer varies from 0 to some upper value that must be determined via
|
|
introspection.
|
|
@roff_stats@In the case of
|
|
@roff_stats@.Dq stats.arenas.<i>.* ,
|
|
@roff_stats@<i> equal to
|
|
@roff_stats@.Dq arenas.narenas
|
|
@roff_stats@can be used to access the summation of statistics from all arenas.
|
|
.Bl -ohang
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "epoch (uint64_t) rw"
|
|
.Bd -ragged -offset indent -compact
|
|
If a value is passed in, refresh the data from which the
|
|
.Fn mallctl*
|
|
functions report values, and increment the epoch.
|
|
Return the current epoch.
|
|
This is useful for detecting whether another thread caused a refresh.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_tcache@.It Sy "tcache.flush (void) --"
|
|
@roff_tcache@.Bd -ragged -offset indent -compact
|
|
@roff_tcache@Flush calling thread's tcache.
|
|
@roff_tcache@This interface releases all cached objects and internal data
|
|
@roff_tcache@structures associated with the calling thread's thread-specific
|
|
@roff_tcache@cache.
|
|
@roff_tcache@Ordinarily, this interface need not be called, since automatic
|
|
@roff_tcache@periodic incremental garbage collection occurs, and the thread
|
|
@roff_tcache@cache is automatically discarded when a thread exits.
|
|
@roff_tcache@However, garbage collection is triggered by allocation activity,
|
|
@roff_tcache@so it is possible for a thread that stops allocating/deallocating
|
|
@roff_tcache@to retain its cache indefinitely, in which case the developer may
|
|
@roff_tcache@find manual flushing useful.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "config.debug (bool) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
--enable-debug was specified during build configuration.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "config.dss (bool) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
--enable-dss was specified during build configuration.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "config.dynamic_page_shift (bool) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
--enable-dynamic-page-shift was specified during build configuration.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "config.fill (bool) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
--enable-fill was specified during build configuration.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "config.lazy_lock (bool) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
--enable-lazy-lock was specified during build configuration.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "config.prof (bool) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
--enable-prof was specified during build configuration.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "config.prof_libgcc (bool) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
--disable-prof-libgcc was not specified during build configuration.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "config.prof_libunwind (bool) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
--enable-prof-libunwind was specified during build configuration.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "config.stats (bool) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
--enable-stats was specified during build configuration.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "config.swap (bool) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
--enable-swap was specified during build configuration.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "config.sysv (bool) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
--enable-sysv was specified during build configuration.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "config.tcache (bool) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
--disable-tcache was not specified during build configuration.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "config.tiny (bool) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
--disable-tiny was not specified during build configuration.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "config.tls (bool) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
--disable-tls was not specified during build configuration.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "config.xmalloc (bool) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
--enable-xmalloc was specified during build configuration.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "opt.abort (bool) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
See the
|
|
.Dq A
|
|
option.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_fill@.It Sy "opt.junk (bool) r-"
|
|
@roff_fill@.Bd -ragged -offset indent -compact
|
|
@roff_fill@See the
|
|
@roff_fill@.Dq J
|
|
@roff_fill@option.
|
|
@roff_fill@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_fill@.It Sy "opt.zero (bool) r-"
|
|
@roff_fill@.Bd -ragged -offset indent -compact
|
|
@roff_fill@See the
|
|
@roff_fill@.Dq Z
|
|
@roff_fill@option.
|
|
@roff_fill@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_xmalloc@.It Sy "opt.xmalloc (bool) r-"
|
|
@roff_xmalloc@.Bd -ragged -offset indent -compact
|
|
@roff_xmalloc@See the
|
|
@roff_xmalloc@.Dq X
|
|
@roff_xmalloc@option.
|
|
@roff_xmalloc@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_tcache@.It Sy "opt.lg_tcache_nslots (size_t) r-"
|
|
@roff_tcache@.Bd -ragged -offset indent -compact
|
|
@roff_tcache@See the
|
|
@roff_tcache@.Dq H
|
|
@roff_tcache@option.
|
|
@roff_tcache@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_tcache@.It Sy "opt.lg_tcache_gc_sweep (ssize_t) r-"
|
|
@roff_tcache@.Bd -ragged -offset indent -compact
|
|
@roff_tcache@See the
|
|
@roff_tcache@.Dq G
|
|
@roff_tcache@option.
|
|
@roff_tcache@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "opt.stats_print (bool) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
See the
|
|
.Dq P
|
|
option.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_prof@.It Sy "opt.prof (bool) r-"
|
|
@roff_prof@.Bd -ragged -offset indent -compact
|
|
@roff_prof@See the
|
|
@roff_prof@.Dq F
|
|
@roff_prof@option.
|
|
@roff_prof@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_prof@.It Sy "opt.lg_prof_bt_max (size_t) r-"
|
|
@roff_prof@.Bd -ragged -offset indent -compact
|
|
@roff_prof@See the
|
|
@roff_prof@.Dq B
|
|
@roff_prof@option.
|
|
@roff_prof@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_prof@.It Sy "opt.lg_prof_interval (size_t) r-"
|
|
@roff_prof@.Bd -ragged -offset indent -compact
|
|
@roff_prof@See the
|
|
@roff_prof@.Dq I
|
|
@roff_prof@option.
|
|
@roff_prof@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_prof@.It Sy "opt.prof_udump (bool) r-"
|
|
@roff_prof@.Bd -ragged -offset indent -compact
|
|
@roff_prof@See the
|
|
@roff_prof@.Dq U
|
|
@roff_prof@option.
|
|
@roff_prof@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_prof@.It Sy "opt.prof_leak (bool) r-"
|
|
@roff_prof@.Bd -ragged -offset indent -compact
|
|
@roff_prof@See the
|
|
@roff_prof@.Dq L
|
|
@roff_prof@option.
|
|
@roff_prof@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "opt.lg_qspace_max (size_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
See the
|
|
.Dq Q
|
|
option.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "opt.lg_cspace_max (size_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
See the
|
|
.Dq C
|
|
option.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "opt.lg_medium_max (size_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
See the
|
|
.Dq M
|
|
option.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "opt.lg_dirty_mult (ssize_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
See the
|
|
.Dq D
|
|
option.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "opt.lg_chunk (size_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
See the
|
|
.Dq K
|
|
option.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "opt.overcommit (bool) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
See the
|
|
.Dq O
|
|
option.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "arenas.narenas (unsigned) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Maximum number of arenas.
|
|
See the
|
|
.Dq N
|
|
option.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "arenas.initialized (bool *) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
An array of arenas.narenas booleans.
|
|
Each boolean indicates whether the corresponding arena is initialized.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "arenas.quantum (size_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Quantum size.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "arenas.cacheline (size_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Assumed cacheline size.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "arenas.subpage (size_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Subpage size class interval.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "arenas.pagesize (size_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Page size.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "arenas.medium (size_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Medium size class interval.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "arenas.chunksize (size_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Chunk size.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "arenas.tspace_min (size_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Minimum tiny size class.
|
|
Tiny size classes are powers of two.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "arenas.tspace_max (size_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Maximum tiny size class.
|
|
Tiny size classes are powers of two.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "arenas.qspace_min (size_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Minimum quantum-spaced size class.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "arenas.qspace_max (size_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Maximum quantum-spaced size class.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "arenas.cspace_min (size_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Minimum cacheline-spaced size class.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "arenas.cspace_max (size_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Maximum cacheline-spaced size class.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "arenas.sspace_min (size_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Minimum subpage-spaced size class.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "arenas.sspace_max (size_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Maximum subpage-spaced size class.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "arenas.medium_min (size_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Minimum medium-spaced size class.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "arenas.medium_max (size_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Maximum medium-spaced size class.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "arenas.ntbins (unsigned) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Number of tiny bin size classes.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "arenas.nqbins (unsigned) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Number of quantum-spaced bin size classes.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "arenas.ncbins (unsigned) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Number of cacheline-spaced bin size classes.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "arenas.nsbins (unsigned) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Number of subpage-spaced bin size classes.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "arenas.nmbins (unsigned) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Number of medium-spaced bin size classes.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "arenas.nbins (unsigned) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Total number of bin size classes.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "arenas.bin.<i>.size (size_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Maximum size supported by size class.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "arenas.bin.<i>.nregs (uint32_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Number of regions per page run.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "arenas.bin.<i>.run_size (size_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Number of bytes per page run.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "arenas.nlruns (size_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Total number of large size classes.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "arenas.lrun.<i>.size (size_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Maximum size supported by this large size class.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_prof@.It Sy "prof.dump (void) --"
|
|
@roff_prof@.Bd -ragged -offset indent -compact
|
|
@roff_prof@Dump a memory profile to a file according to the pattern
|
|
@roff_prof@.Pa <prefix>.<pid>.<seq>.m<mseq>.heap ,
|
|
@roff_prof@where
|
|
@roff_prof@.Pa <prefix>
|
|
@roff_prof@is controlled by the
|
|
@roff_prof@JEMALLOC_PROF_PREFIX
|
|
@roff_prof@environment variable.
|
|
@roff_prof@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_prof@.It Sy "prof.interval (uint64_t) r-"
|
|
@roff_prof@.Bd -ragged -offset indent -compact
|
|
@roff_prof@Average number of bytes allocated between inverval-based profile
|
|
@roff_prof@dumps.
|
|
@roff_prof@See the
|
|
@roff_prof@.Dq I
|
|
@roff_prof@option for additional information.
|
|
@roff_prof@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.allocated (size_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Total number of bytes allocated by the application.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.active (size_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Total number of bytes in active pages allocated by the application.
|
|
@roff_stats@This is a multiple of the page size, and greater than or equal to
|
|
@roff_stats@.Dq stats.allocated .
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.mapped (size_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Total number of bytes in chunks mapped on behalf of the application.
|
|
@roff_stats@This is a multiple of the chunk size, and is at least as large as
|
|
@roff_stats@.Dq stats.active .
|
|
@roff_stats@@roff_swap@This does not include inactive chunks backed by swap
|
|
@roff_stats@@roff_swap@files.
|
|
@roff_stats@@roff_dss@This does not include inactive chunks embedded in the DSS.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.chunks.current (size_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Total number of chunks actively mapped on behalf of the application.
|
|
@roff_stats@@roff_swap@This does not include inactive chunks backed by swap
|
|
@roff_stats@@roff_swap@files.
|
|
@roff_stats@@roff_dss@This does not include inactive chunks embedded in the DSS.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.chunks.total (uint64_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Cumulative number of chunks allocated.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.chunks.high (size_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Maximum number of active chunks at any time thus far.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.huge.allocated (size_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Number of bytes currently allocated by huge objects.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.huge.nmalloc (uint64_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Cumulative number of huge allocation requests.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.huge.ndalloc (uint64_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Cumulative number of huge deallocation requests.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "stats.arenas.<i>.pactive (size_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Number of pages in active runs.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "stats.arenas.<i>.pdirty (size_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Number of pages within unused runs that are potentially dirty, and for which
|
|
.Fn madvise "..." "MADV_DONTNEED"
|
|
has not been called.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.arenas.<i>.mapped (size_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Number of mapped bytes.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.arenas.<i>.npurge (uint64_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Number of dirty page purge sweeps performed.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.arenas.<i>.nmadvise (uint64_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Number of
|
|
@roff_stats@.Fn madvise "..." "MADV_DONTNEED"
|
|
@roff_stats@calls made to purge dirty pages.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.arenas.<i>.npurged (uint64_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Number of pages purged.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.arenas.<i>.small.allocated (size_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Number of bytes currently allocated by small objects.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.arenas.<i>.small.nmalloc (uint64_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Cumulative number of small allocation requests.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.arenas.<i>.small.ndalloc (uint64_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Cumulative number of small deallocation requests.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.arenas.<i>.medium.allocated (size_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Number of bytes currently allocated by medium objects.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.arenas.<i>.medium.nmalloc (uint64_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Cumulative number of medium allocation requests.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.arenas.<i>.medium.ndalloc (uint64_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Cumulative number of medium deallocation requests.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.arenas.<i>.large.allocated (size_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Number of bytes currently allocated by large objects.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.arenas.<i>.large.nmalloc (uint64_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Cumulative number of large allocation requests.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.arenas.<i>.large.ndalloc (uint64_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Cumulative number of large deallocation requests.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.arenas.<i>.bins.<j>.nrequests (uint64_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Cumulative number of allocation requests.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@@roff_tcache@.It Sy "stats.arenas.<i>.bins.<j>.nfills (uint64_t) r-"
|
|
@roff_stats@@roff_tcache@.Bd -ragged -offset indent -compact
|
|
@roff_stats@@roff_tcache@Cumulative number of tcache fills.
|
|
@roff_stats@@roff_tcache@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@@roff_tcache@.It Sy "stats.arenas.<i>.bins.<j>.nflushes (uint64_t) r-"
|
|
@roff_stats@@roff_tcache@.Bd -ragged -offset indent -compact
|
|
@roff_stats@@roff_tcache@Cumulative number of tcache flushes.
|
|
@roff_stats@@roff_tcache@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.arenas.<i>.bins.<j>.nruns (uint64_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Cumulative number of runs created.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.arenas.<i>.bins.<j>.nreruns (uint64_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Cumulative number of times the current run from which to allocate
|
|
@roff_stats@changed.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.arenas.<i>.bins.<j>.highruns (size_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Maximum number of runs at any time thus far.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.arenas.<i>.bins.<j>.curruns (size_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Current number of runs.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.arenas.<i>.lruns.<j>.nrequests (uint64_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Cumulative number of allocation requests for this size class.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.arenas.<i>.lruns.<j>.highruns (size_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Maximum number of runs at any time thus far for this size class.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.arenas.<i>.lruns.<j>.curruns (size_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Current number of runs for this size class.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@@roff_swap@.It Sy "swap.avail (size_t) r-"
|
|
@roff_stats@@roff_swap@.Bd -ragged -offset indent -compact
|
|
@roff_stats@@roff_swap@Number of swap file bytes that are currently not
|
|
@roff_stats@@roff_swap@associated with any chunk (i.e. mapped, but otherwise
|
|
@roff_stats@@roff_swap@completely unmanaged).
|
|
@roff_stats@@roff_swap@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_swap@.It Sy "swap.prezeroed (bool) rw"
|
|
@roff_swap@.Bd -ragged -offset indent -compact
|
|
@roff_swap@If true, the allocator assumes that the swap file(s) contain nothing
|
|
@roff_swap@but nil bytes.
|
|
@roff_swap@If this assumption is violated, allocator behavior is undefined.
|
|
@roff_swap@This value becomes read-only after
|
|
@roff_swap@.Dq swap.fds
|
|
@roff_swap@is successfully written to.
|
|
@roff_swap@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_swap@.It Sy "swap.nfds (size_t) r-"
|
|
@roff_swap@.Bd -ragged -offset indent -compact
|
|
@roff_swap@Number of file descriptors in use for swap.
|
|
@roff_swap@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_swap@.It Sy "swap.fds (int *) r-"
|
|
@roff_swap@.Bd -ragged -offset indent -compact
|
|
@roff_swap@When written to, the files associated with the specified file
|
|
@roff_swap@descriptors are contiguously mapped via
|
|
@roff_swap@.Xr mmap 2 .
|
|
@roff_swap@The resulting virtual memory region is preferred over anonymous
|
|
@roff_swap@.Xr mmap 2
|
|
@roff_swap@@roff_dss@and
|
|
@roff_swap@@roff_dss@.Xr sbrk 2
|
|
@roff_swap@memory.
|
|
@roff_swap@Note that if a file's size is not a multiple of the page size, it is
|
|
@roff_swap@automatically truncated to the nearest page size multiple.
|
|
@roff_swap@See the
|
|
@roff_swap@.Dq swap.prezeroed
|
|
@roff_swap@interface for specifying that the files are pre-zeroed.
|
|
@roff_swap@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.El
|
|
.Sh DEBUGGING MALLOC PROBLEMS
|
|
The first thing to do is to set the
|
|
.Dq A
|
|
option.
|
|
This option forces a coredump (if possible) at the first sign of trouble,
|
|
rather than the normal policy of trying to continue if at all possible.
|
|
.Pp
|
|
It is probably also a good idea to recompile the program with suitable
|
|
options and symbols for debugger support.
|
|
.Pp
|
|
@roff_fill@If the program starts to give unusual results, coredump or generally
|
|
@roff_fill@behave differently without emitting any of the messages mentioned in
|
|
@roff_fill@the next section, it is likely because it depends on the storage
|
|
@roff_fill@being filled with zero bytes.
|
|
@roff_fill@Try running it with the
|
|
@roff_fill@.Dq Z
|
|
@roff_fill@option set;
|
|
@roff_fill@if that improves the situation, this diagnosis has been confirmed.
|
|
@roff_fill@If the program still misbehaves,
|
|
@roff_fill@the likely problem is accessing memory outside the allocated area.
|
|
@roff_fill@.Pp
|
|
@roff_fill@Alternatively, if the symptoms are not easy to reproduce, setting the
|
|
@roff_fill@.Dq J
|
|
@roff_fill@option may help provoke the problem.
|
|
@roff_fill@.Pp
|
|
Unfortunately this implementation does not provide much detail about
|
|
the problems it detects; the performance impact for storing such information
|
|
would be prohibitive.
|
|
There are a number of allocator implementations available on the Internet
|
|
which focus on detecting and pinpointing problems by trading performance for
|
|
extra sanity checks and detailed diagnostics.
|
|
.Sh DIAGNOSTIC MESSAGES
|
|
If any of the memory allocation/deallocation functions detect an error or
|
|
warning condition, a message will be printed to file descriptor
|
|
.Dv STDERR_FILENO .
|
|
Errors will result in the process dumping core.
|
|
If the
|
|
.Dq A
|
|
option is set, all warnings are treated as errors.
|
|
.Pp
|
|
The
|
|
.Va @jemalloc_prefix@malloc_message
|
|
variable allows the programmer to override the function which emits the text
|
|
strings forming the errors and warnings if for some reason the
|
|
.Dv STDERR_FILENO
|
|
file descriptor is not suitable for this.
|
|
.Va @jemalloc_prefix@malloc_message
|
|
takes the
|
|
.Fa w4opaque
|
|
pointer argument that is
|
|
.Dv NULL
|
|
unless overridden by the arguments in a call to
|
|
.Fn @jemalloc_prefix@malloc_stats_print ,
|
|
followed by four string pointers.
|
|
Please note that doing anything which tries to allocate memory in this function
|
|
is likely to result in a crash or deadlock.
|
|
.Pp
|
|
All messages are prefixed by
|
|
.Dq <jemalloc>: .
|
|
.Sh RETURN VALUES
|
|
The
|
|
.Fn @jemalloc_prefix@malloc
|
|
and
|
|
.Fn @jemalloc_prefix@calloc
|
|
functions return a pointer to the allocated memory if successful; otherwise
|
|
a
|
|
.Dv NULL
|
|
pointer is returned and
|
|
.Va errno
|
|
is set to
|
|
.Er ENOMEM .
|
|
.Pp
|
|
The
|
|
.Fn @jemalloc_prefix@posix_memalign
|
|
function returns the value 0 if successful; otherwise it returns an error value.
|
|
The
|
|
.Fn @jemalloc_prefix@posix_memalign
|
|
function will fail if:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EINVAL
|
|
The
|
|
.Fa alignment
|
|
parameter is not a power of 2 at least as large as
|
|
.Fn sizeof "void *" .
|
|
.It Bq Er ENOMEM
|
|
Memory allocation error.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn @jemalloc_prefix@realloc
|
|
function returns a pointer, possibly identical to
|
|
.Fa ptr ,
|
|
to the allocated memory
|
|
if successful; otherwise a
|
|
.Dv NULL
|
|
pointer is returned, and
|
|
.Va errno
|
|
is set to
|
|
.Er ENOMEM
|
|
if the error was the result of an allocation failure.
|
|
The
|
|
.Fn @jemalloc_prefix@realloc
|
|
function always leaves the original buffer intact
|
|
when an error occurs.
|
|
.Pp
|
|
The
|
|
.Fn @jemalloc_prefix@free
|
|
function returns no value.
|
|
.Pp
|
|
The
|
|
.Fn @jemalloc_prefix@malloc_usable_size
|
|
function returns the usable size of the allocation pointed to by
|
|
.Fa ptr .
|
|
.Pp
|
|
The
|
|
.Fn @jemalloc_prefix@mallctl ,
|
|
.Fn @jemalloc_prefix@mallctlnametomib ,
|
|
and
|
|
.Fn @jemalloc_prefix@mallctlbymib
|
|
functions return 0 on success; otherwise they return an error value.
|
|
The functions will fail if:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EINVAL
|
|
.Fa newp
|
|
is
|
|
.Dv non-NULL ,
|
|
and
|
|
.Fa newlen
|
|
is too large or too small.
|
|
Alternatively,
|
|
.Fa *oldlenp
|
|
is too large or too small; in this case as much data as possible are read
|
|
despite the error.
|
|
.It Bq Er ENOMEM
|
|
.Fa *oldlenp
|
|
is too short to hold the requested value.
|
|
.It Bq Er ENOENT
|
|
.Fa name
|
|
or
|
|
.Fa mib
|
|
specifies an unknown/invalid value.
|
|
.It Bq Er EPERM
|
|
Attempt to read or write void value, or attempt to write read-only value.
|
|
.It Bq Er EAGAIN
|
|
A memory allocation failure occurred.
|
|
.It Bq Er EFAULT
|
|
An interface with side effects failed in some way not directly related to
|
|
.Fn mallctl*
|
|
read/write processing.
|
|
.El
|
|
.Sh ENVIRONMENT
|
|
The following environment variables affect the execution of the allocation
|
|
functions:
|
|
@roff_prof@.Bl -tag -width ".Ev JEMALLOC_PROF_PREFIX"
|
|
@roff_no_prof@.Bl -tag -width ".Ev JEMALLOC_OPTIONS"
|
|
.It Ev JEMALLOC_OPTIONS
|
|
If the environment variable
|
|
.Ev JEMALLOC_OPTIONS
|
|
is set, the characters it contains will be interpreted as flags to the
|
|
allocation functions.
|
|
@roff_prof@.It Ev JEMALLOC_PROF_PREFIX
|
|
@roff_prof@If the environment variable
|
|
@roff_prof@.Ev JEMALLOC_PROF_PREFIX
|
|
@roff_prof@is set, use it as the filename prefix for profile dumps; otherwise
|
|
@roff_prof@use
|
|
@roff_prof@.Pa jeprof
|
|
@roff_prof@as the prefix.
|
|
.El
|
|
.Sh EXAMPLES
|
|
To dump core whenever a problem occurs:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
ln -s 'A' /etc/jemalloc.conf
|
|
.Ed
|
|
.Pp
|
|
To specify in the source a chunk size that is twice the default:
|
|
.Bd -literal -offset indent
|
|
@jemalloc_prefix@malloc_options = "K";
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr madvise 2 ,
|
|
.Xr mmap 2 ,
|
|
@roff_dss@.Xr sbrk 2 ,
|
|
.Xr alloca 3 ,
|
|
.Xr atexit 3 ,
|
|
.Xr getpagesize 3
|
|
.Sh STANDARDS
|
|
The
|
|
.Fn @jemalloc_prefix@malloc ,
|
|
.Fn @jemalloc_prefix@calloc ,
|
|
.Fn @jemalloc_prefix@realloc
|
|
and
|
|
.Fn @jemalloc_prefix@free
|
|
functions conform to
|
|
.St -isoC .
|
|
.Pp
|
|
The
|
|
.Fn @jemalloc_prefix@posix_memalign
|
|
function conforms to
|
|
.St -p1003.1-2001 .
|