1689 lines
65 KiB
Groff
1689 lines
65 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 November 5, 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 ,
|
|
.Nm @jemalloc_prefix@allocm ,
|
|
.Nm @jemalloc_prefix@rallocm ,
|
|
.Nm @jemalloc_prefix@sallocm ,
|
|
.Nm @jemalloc_prefix@dallocm
|
|
.Nd general purpose memory allocation functions
|
|
.Sh LIBRARY
|
|
.Sy libjemalloc@install_suffix@
|
|
.Pp
|
|
This manual describes jemalloc @jemalloc_version@.
|
|
More information can be found at the
|
|
.UR http://\:www.canonware.com/\:jemalloc/
|
|
jemalloc website
|
|
.UE .
|
|
.Sh SYNOPSIS
|
|
.In stdlib.h
|
|
.In jemalloc/jemalloc@install_suffix@.h
|
|
.Ss Standard API
|
|
.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"
|
|
.Ss Non-standard API
|
|
.Ft size_t
|
|
.Fn @jemalloc_prefix@malloc_usable_size "const void *ptr"
|
|
.Ft void
|
|
.Fn @jemalloc_prefix@malloc_stats_print "void (*write_cb)(void *" "const char *)" "void *cbopaque" "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" "size_t *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_conf ;
|
|
.Ft void
|
|
.Fn \*(lp*@jemalloc_prefix@malloc_message\*(rp "void *cbopaque" "const char *s"
|
|
.Ss Experimental API
|
|
.Ft int
|
|
.Fn @jemalloc_prefix@allocm "void **ptr" "size_t *rsize" "size_t size" "int flags"
|
|
.Ft int
|
|
.Fn @jemalloc_prefix@rallocm "void **ptr" "size_t *rsize" "size_t size" "size_t extra" "int flags"
|
|
.Ft int
|
|
.Fn @jemalloc_prefix@sallocm "const void *ptr" "size_t *rsize" "int flags"
|
|
.Ft int
|
|
.Fn @jemalloc_prefix@dallocm "void *ptr" "int flags"
|
|
.Sh DESCRIPTION
|
|
.Ss Standard API
|
|
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.
|
|
.Ss Non-standard API
|
|
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 write_cb
|
|
callback function pointer and
|
|
.Fa cbopaque
|
|
data passed to
|
|
.Fn write_cb ,
|
|
or
|
|
.Fn @jemalloc_prefix@malloc_message
|
|
if
|
|
.Fa write_cb
|
|
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
|
|
.Ss Experimental API
|
|
The experimental API is subject to change or removal without regard for
|
|
backward compatibility.
|
|
.Pp
|
|
The
|
|
.Fn @jemalloc_prefix@allocm ,
|
|
.Fn @jemalloc_prefix@rallocm ,
|
|
.Fn @jemalloc_prefix@sallocm ,
|
|
and
|
|
.Fn @jemalloc_prefix@dallocm
|
|
functions all have a
|
|
.Fa flags
|
|
argument that can be used to specify options.
|
|
The functions only check the options that are contextually relevant.
|
|
Use bitwise or (|) operations to specify one or more of the following:
|
|
.Bl -tag -width ".Dv ALLOCM_LG_ALIGN(la)"
|
|
.It ALLOCM_LG_ALIGN(la)
|
|
Align the memory allocation to start at an address that is a multiple of
|
|
(1 <<
|
|
.Fa la ) .
|
|
This macro does not validate that
|
|
.Fa la
|
|
is within the valid range.
|
|
.It ALLOCM_ALIGN(a)
|
|
Align the memory allocation to start at an address that is a multiple of
|
|
.Fa a ,
|
|
where
|
|
.Fa a
|
|
is a power of two.
|
|
This macro does not validate that
|
|
.Fa a
|
|
is a power of 2.
|
|
.It ALLOCM_ZERO
|
|
Initialize newly allocated memory to contain zero bytes.
|
|
In the growing reallocation case, the real size prior to reallocation defines
|
|
the boundary between untouched bytes and those that are initialized to contain
|
|
zero bytes.
|
|
If this option is absent, newly allocated memory is uninitialized.
|
|
.It ALLOCM_NO_MOVE
|
|
For reallocation, fail rather than moving the object.
|
|
This constraint can apply to both growth and shrinkage.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn @jemalloc_prefix@allocm
|
|
function allocates at least
|
|
.Fa size
|
|
bytes of memory, sets
|
|
.Fa *ptr
|
|
to the base address of the allocation, and sets
|
|
.Fa *rsize
|
|
to the real size of the allocation if
|
|
.Fa rsize
|
|
is not
|
|
.Dv NULL .
|
|
.Pp
|
|
The
|
|
.Fn @jemalloc_prefix@rallocm
|
|
function resizes the allocation at
|
|
.Fa *ptr
|
|
to be at least
|
|
.Fa size
|
|
bytes, sets
|
|
.Fa *ptr
|
|
to the base address of the allocation if it moved, and sets
|
|
.Fa *rsize
|
|
to the real size of the allocation if
|
|
.Fa rsize
|
|
is not
|
|
.Dv NULL .
|
|
If
|
|
.Fa extra
|
|
is non-zero, an attempt is made to resize the allocation to be at least
|
|
.Fa ( size
|
|
+
|
|
.Fa extra )
|
|
bytes, though inability to allocate the extra byte(s) will not by itself result
|
|
in failure.
|
|
Behavior is undefined if
|
|
.Fa ( size
|
|
+
|
|
.Fa extra
|
|
>
|
|
.Dv SIZE_T_MAX ) .
|
|
.Pp
|
|
The
|
|
.Fn @jemalloc_prefix@sallocm
|
|
function sets
|
|
.Fa *rsize
|
|
to the real size of the allocation.
|
|
.Pp
|
|
The
|
|
.Fn @jemalloc_prefix@dallocm
|
|
function causes the memory referenced by
|
|
.Fa ptr
|
|
to be made available for future allocations.
|
|
.Sh TUNING
|
|
Once, when the first call is made to one of the memory allocation routines, the
|
|
allocator initializes its internals based in part on various options that can
|
|
be specified at compile- or run-time.
|
|
.Pp
|
|
The string pointed to by the global variable
|
|
.Va @jemalloc_prefix@malloc_conf ,
|
|
the
|
|
.Dq name
|
|
of the file referenced by the symbolic link named
|
|
.Pa /etc/@jemalloc_prefix@malloc.conf ,
|
|
and the value of the environment variable
|
|
.Ev @jemalloc_cprefix@MALLOC_CONF ,
|
|
will be interpreted, in that order, from left to right as options.
|
|
.Pp
|
|
An options string is a comma-separated list of option:value pairs.
|
|
There is one key corresponding to each
|
|
.Dq opt.*
|
|
mallctl.
|
|
For example,
|
|
.Dq abort:true,narenas:1
|
|
sets the
|
|
.Dq opt.abort
|
|
and
|
|
.Dq opt.narenas
|
|
options.
|
|
Some options have boolean values (true/false), others have integer values (base
|
|
8, 10, or 16, depending on prefix), and yet others have raw string values.
|
|
.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 large objects, in order to
|
|
@roff_tcache@make it possible to completely avoid synchronization for most
|
|
@roff_tcache@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 three categories according to size: small, large,
|
|
and huge.
|
|
Small objects are smaller than one page.
|
|
Large objects are smaller than the chunk size.
|
|
Huge objects are a multiple of the chunk size.
|
|
Small 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 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 objects are managed in groups by page runs.
|
|
Each run maintains a frontier and free list to track 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 opt.lg_qspace_max
|
|
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 opt.lg_cspace_max
|
|
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 small enough to fit in an arena-managed chunk (see the
|
|
.Dq opt.lg_chunk
|
|
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, or specify cacheline alignment when allocating.
|
|
.Pp
|
|
Assuming 4 MiB chunks, 4 KiB pages, and a 16-byte quantum on a 64-bit system,
|
|
the size classes in each category are as follows:
|
|
.\"-----------------------------------------------------------------------------
|
|
.TS
|
|
allbox tab(;);
|
|
LLL
|
|
LLL
|
|
^LL
|
|
^LL
|
|
^LL
|
|
LsL
|
|
LsL.
|
|
Category;Subcategory;Size
|
|
@roff_tiny@Small;Tiny;[8]
|
|
@roff_no_tiny@Small;Tiny;[disabled]
|
|
;Quantum-spaced;[16, 32, 48, ..., 128]
|
|
;Cacheline-spaced;[192, 256, 320, ..., 512]
|
|
;Sub-page-spaced;[768, 1024, 1280, ..., 3840]
|
|
Large;[4 KiB, 8 KiB, 12 KiB, ..., 4072 KiB]
|
|
Huge;[4 MiB, 8 MiB, 12 MiB, ...]
|
|
.TE
|
|
.\"-----------------------------------------------------------------------------
|
|
.Sh MALLCTL NAMESPACE
|
|
The following names are defined in the namespace accessible via the
|
|
.Fn @jemalloc_prefix@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.
|
|
.Pp
|
|
Take special note of the
|
|
.Dq epoch
|
|
mallctl, which controls refreshing of cached dynamic statistics.
|
|
.Bl -ohang
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "version (const char *) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Return the jemalloc version string.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "epoch (uint64_t) rw"
|
|
.Bd -ragged -offset indent -compact
|
|
If a value is passed in, refresh the data from which the
|
|
.Fn @jemalloc_prefix@mallctl*
|
|
functions report values, and increment the epoch.
|
|
Return the current epoch.
|
|
This is useful for detecting whether another thread caused a refresh.
|
|
.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
|
|
Abort-on-warning enabled/disabled.
|
|
If true, most warnings are fatal.
|
|
The process will call
|
|
.Xr abort 3
|
|
in these cases.
|
|
This option is
|
|
@roff_debug@enabled
|
|
@roff_no_debug@disabled
|
|
by default.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "opt.lg_qspace_max (size_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Size (log base 2) 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 (2^7).
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "opt.lg_cspace_max (size_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Size (log base 2) 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 (2^9).
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "opt.lg_chunk (size_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Virtual memory chunk size (log base 2).
|
|
The default chunk size is 4 MiB (2^22).
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "opt.narenas (size_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Maximum number of arenas to use.
|
|
The default maximum number of arenas is four times the number of CPUs, or one
|
|
if there is a single CPU.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "opt.lg_dirty_mult (ssize_t) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Per-arena minimum ratio (log base 2) of active to dirty pages.
|
|
Some dirty unused pages may be allowed to accumulate, within the limit set by
|
|
the ratio (or one chunk worth of dirty pages, whichever is greater), before
|
|
informing the kernel about some of those pages via
|
|
.Xr madvise 2
|
|
or a similar system call.
|
|
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 (2^5:1); an option value of -1 will disable
|
|
dirty page purging.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "opt.stats_print (bool) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Enable/disable statistics printing at exit.
|
|
If enabled, the
|
|
.Fn @jemalloc_prefix@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.
|
|
This option is disabled by default.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_fill@.It Sy "opt.junk (bool) r-"
|
|
@roff_fill@.Bd -ragged -offset indent -compact
|
|
@roff_fill@Junk filling enabled/disabled.
|
|
@roff_fill@If enabled, each byte of uninitialized allocated memory will be
|
|
@roff_fill@initialized to 0xa5.
|
|
@roff_fill@All deallocated memory will be initialized to 0x5a.
|
|
@roff_fill@This is intended for debugging and will impact performance
|
|
@roff_fill@negatively.
|
|
@roff_fill@This option is
|
|
@roff_fill@@roff_debug@enabled
|
|
@roff_fill@@roff_no_debug@disabled
|
|
@roff_fill@by default.
|
|
@roff_fill@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_fill@.It Sy "opt.zero (bool) r-"
|
|
@roff_fill@.Bd -ragged -offset indent -compact
|
|
@roff_fill@Zero filling enabled/disabled.
|
|
@roff_fill@If enabled, each byte of uninitialized allocated memory will be
|
|
@roff_fill@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.
|
|
@roff_fill@This option is disabled by default.
|
|
@roff_fill@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_sysv@.It Sy "opt.sysv (bool) r-"
|
|
@roff_sysv@.Bd -ragged -offset indent -compact
|
|
@roff_sysv@If enabled, 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 opt.xmalloc
|
|
@roff_sysv@@roff_xmalloc@option.
|
|
@roff_sysv@This option is disabled by default.
|
|
@roff_sysv@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_xmalloc@.It Sy "opt.xmalloc (bool) r-"
|
|
@roff_xmalloc@.Bd -ragged -offset indent -compact
|
|
@roff_xmalloc@Abort-on-out-of-memory enabled/disabled.
|
|
@roff_xmalloc@If enabled, rather than returning failure for any allocation
|
|
@roff_xmalloc@function, display a 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@If an application is designed to depend on this behavior, set the
|
|
@roff_xmalloc@option at compile time by including the following in the source
|
|
@roff_xmalloc@code:
|
|
@roff_xmalloc@.Bd -literal -offset indent
|
|
@roff_xmalloc@@jemalloc_prefix@malloc_conf = "xmalloc:true";
|
|
@roff_xmalloc@.Ed
|
|
@roff_xmalloc@.Pp
|
|
@roff_xmalloc@This option is disabled by default.
|
|
@roff_xmalloc@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_tcache@.It Sy "opt.tcache (bool) r-"
|
|
@roff_tcache@.Bd -ragged -offset indent -compact
|
|
@roff_tcache@Thread-specific caching enabled/disabled.
|
|
@roff_tcache@When there are multiple threads, each thread uses a
|
|
@roff_tcache@thread-specific cache for objects up to a certain size.
|
|
@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 opt.lg_tcache_gc_sweep
|
|
@roff_tcache@and
|
|
@roff_tcache@.Dq opt.tcache_max
|
|
@roff_tcache@options for related tuning information.
|
|
@roff_tcache@This option is enabled by default.
|
|
@roff_tcache@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_tcache@.It Sy "opt.lg_tcache_gc_sweep (ssize_t) r-"
|
|
@roff_tcache@.Bd -ragged -offset indent -compact
|
|
@roff_tcache@Approximate interval (log base 2) between full thread-specific
|
|
@roff_tcache@cache garbage collection sweeps, counted in terms of
|
|
@roff_tcache@thread-specific cache allocation/deallocation events.
|
|
@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 (2^13); setting this option to
|
|
@roff_tcache@-1 will disable garbage collection.
|
|
@roff_tcache@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_tcache@.It Sy "opt.lg_tcache_max (size_t) r-"
|
|
@roff_tcache@.Bd -ragged -offset indent -compact
|
|
@roff_tcache@Maximum size class (log base 2) to cache in the thread-specific
|
|
@roff_tcache@cache.
|
|
@roff_tcache@At a minimum, all small size classes are cached, and at a maximum
|
|
@roff_tcache@all large size classes are cached.
|
|
@roff_tcache@The default maximum is 32 KiB (2^15).
|
|
@roff_tcache@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_prof@.It Sy "opt.prof (bool) r-"
|
|
@roff_prof@.Bd -ragged -offset indent -compact
|
|
@roff_prof@Memory profiling enabled/disabled.
|
|
@roff_prof@If enabled, 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@.Dq opt.prof_prefix
|
|
@roff_prof@option.
|
|
@roff_prof@See the
|
|
@roff_prof@.Dq opt.lg_prof_bt_max
|
|
@roff_prof@option for backtrace depth control.
|
|
@roff_prof@See the
|
|
@roff_prof@.Dq opt.prof_active
|
|
@roff_prof@option for on-the-fly activation/deactivation.
|
|
@roff_prof@See the
|
|
@roff_prof@.Dq opt.lg_prof_sample
|
|
@roff_prof@option for probabilistic sampling control.
|
|
@roff_prof@See the
|
|
@roff_prof@.Dq opt.prof_accum
|
|
@roff_prof@option for control of cumulative sample reporting.
|
|
@roff_prof@See the
|
|
@roff_prof@.Dq opt.lg_prof_tcmax
|
|
@roff_prof@option for control of per thread backtrace caching.
|
|
@roff_prof@See the
|
|
@roff_prof@.Dq opt.lg_prof_interval
|
|
@roff_prof@option for information on interval-triggered profile dumping, and the
|
|
@roff_prof@.Dq opt.prof_gdump
|
|
@roff_prof@option for information on high-water-triggered profile dumping.
|
|
@roff_prof@Profile output is compatible with the included pprof Perl script,
|
|
@roff_prof@which originates from the
|
|
@roff_prof@.UR http://\:code.google.com/\:p/\:google-perftools/
|
|
@roff_prof@google-perftools package
|
|
@roff_prof@.UE .
|
|
@roff_prof@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_prof@.It Sy "opt.prof_prefix (const char *) r-"
|
|
@roff_prof@.Bd -ragged -offset indent -compact
|
|
@roff_prof@Filename prefix for profile dumps.
|
|
@roff_prof@If the prefix is set to the empty string, no automatic dumps will
|
|
@roff_prof@occur; this is primarily useful for disabling the automatic final
|
|
@roff_prof@heap dump (which also disables leak reporting, if enabled).
|
|
@roff_prof@The default prefix is
|
|
@roff_prof@.Pa jeprof .
|
|
@roff_prof@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_prof@.It Sy "opt.lg_prof_bt_max (size_t) r-"
|
|
@roff_prof@.Bd -ragged -offset indent -compact
|
|
@roff_prof@Maximum backtrace depth (log base 2) when profiling memory
|
|
@roff_prof@allocation activity.
|
|
@roff_prof@The default is 128 (2^7).
|
|
@roff_prof@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_prof@.It Sy "opt.prof_active (bool) r-"
|
|
@roff_prof@.Bd -ragged -offset indent -compact
|
|
@roff_prof@Profiling activated/deactivated.
|
|
@roff_prof@This is a secondary control mechanism that makes it possible to
|
|
@roff_prof@start the application with profiling enabled (see the
|
|
@roff_prof@.Dq opt.prof
|
|
@roff_prof@option) but inactive, then toggle profiling at any time during
|
|
@roff_prof@program execution with the
|
|
@roff_prof@.Dq prof.active
|
|
@roff_prof@mallctl.
|
|
@roff_prof@This option is enabled by default.
|
|
@roff_prof@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_prof@.It Sy "opt.lg_prof_sample (ssize_t) r-"
|
|
@roff_prof@.Bd -ragged -offset indent -compact
|
|
@roff_prof@Average interval (log base 2) between allocation samples, as
|
|
@roff_prof@measured in bytes of allocation activity.
|
|
@roff_prof@Increasing the sampling interval decreases profile fidelity, but
|
|
@roff_prof@also decreases the computational overhead.
|
|
@roff_prof@The default sample interval is 1 (2^0) (i.e. all allocations are
|
|
@roff_prof@sampled).
|
|
@roff_prof@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_prof@.It Sy "opt.prof_accum (bool) r-"
|
|
@roff_prof@.Bd -ragged -offset indent -compact
|
|
@roff_prof@Reporting of cumulative object/byte counts in profile dumps
|
|
@roff_prof@enabled/disabled.
|
|
@roff_prof@If this option is enabled, every unique backtrace must be stored for
|
|
@roff_prof@the duration of execution.
|
|
@roff_prof@Depending on the application, this can impose a large memory
|
|
@roff_prof@overhead, and the cumulative counts are not always of interest.
|
|
@roff_prof@See the
|
|
@roff_prof@.Dq opt.lg_prof_tcmax
|
|
@roff_prof@option for control of per thread backtrace caching, which has
|
|
@roff_prof@important interactions.
|
|
@roff_prof@This option is enabled by default.
|
|
@roff_prof@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_prof@.It Sy "opt.lg_prof_tcmax (ssize_t) r-"
|
|
@roff_prof@.Bd -ragged -offset indent -compact
|
|
@roff_prof@Maximum per thread backtrace cache (log base 2) used for heap
|
|
@roff_prof@profiling.
|
|
@roff_prof@A backtrace can only be discarded if the
|
|
@roff_prof@.Dq opt.prof_accum
|
|
@roff_prof@option is disabled, and no thread caches currently refer to the
|
|
@roff_prof@backtrace.
|
|
@roff_prof@Therefore, a backtrace cache limit should be imposed if the
|
|
@roff_prof@intention is to limit how much memory is used by backtraces.
|
|
@roff_prof@By default, no limit is imposed (encoded as -1).
|
|
@roff_prof@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_prof@.It Sy "opt.lg_prof_interval (ssize_t) r-"
|
|
@roff_prof@.Bd -ragged -offset indent -compact
|
|
@roff_prof@Average interval (log base 2) 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@.Dq opt.prof_prefix
|
|
@roff_prof@option.
|
|
@roff_prof@By default, interval-triggered profile dumping is disabled (encoded
|
|
@roff_prof@as -1).
|
|
@roff_prof@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_prof@.It Sy "opt.prof_gdump (bool) r-"
|
|
@roff_prof@.Bd -ragged -offset indent -compact
|
|
@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@.Dq opt.prof_prefix
|
|
@roff_prof@option.
|
|
@roff_prof@This option is disabled by default.
|
|
@roff_prof@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_prof@.It Sy "opt.prof_leak (bool) r-"
|
|
@roff_prof@.Bd -ragged -offset indent -compact
|
|
@roff_prof@Leak reporting enabled/disabled.
|
|
@roff_prof@If enabled, use an
|
|
@roff_prof@.Xr atexit 3
|
|
@roff_prof@function to report memory leaks detected by allocation sampling.
|
|
@roff_prof@See the
|
|
@roff_prof@.Dq opt.lg_prof_bt_max
|
|
@roff_prof@option for backtrace depth control.
|
|
@roff_prof@See the
|
|
@roff_prof@.Dq opt.prof
|
|
@roff_prof@option for information on analyzing heap profile output.
|
|
@roff_prof@This option is disabled by default.
|
|
@roff_prof@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "opt.overcommit (bool) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
@roff_swap@Over-commit enabled/disabled.
|
|
@roff_swap@If enabled, 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.
|
|
.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 "thread.arena (unsigned) rw"
|
|
.Bd -ragged -offset indent -compact
|
|
Get or set the arena associated with the calling thread.
|
|
The arena index must be less than the maximum number of arenas (see the
|
|
.Dq arenas.narenas
|
|
mallctl).
|
|
If the specified arena was not initialized beforehand (see the
|
|
.Dq arenas.initialized
|
|
mallctl), it will be automatically initialized as a side effect of calling this
|
|
interface.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "thread.allocated (uint64_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Get the total number of bytes ever allocated by the calling thread.
|
|
@roff_stats@This counter has the potential to wrap around; it is up to the
|
|
@roff_stats@application to appropriately interpret the counter in such cases.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "thread.deallocated (uint64_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Get the total number of bytes ever deallocated by the calling
|
|
@roff_stats@thread.
|
|
@roff_stats@This counter has the potential to wrap around; it is up to the
|
|
@roff_stats@application to appropriately interpret the counter in such cases.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "arenas.narenas (unsigned) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Maximum number of arenas.
|
|
.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.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
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_tcache@.It Sy "arenas.tcache_max (size_t) r-"
|
|
@roff_tcache@.Bd -ragged -offset indent -compact
|
|
@roff_tcache@Maximum thread-cached size class.
|
|
@roff_tcache@.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.nbins (unsigned) r-"
|
|
.Bd -ragged -offset indent -compact
|
|
Total number of bin size classes.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_tcache@.It Sy "arenas.nhbins (unsigned) r-"
|
|
@roff_tcache@.Bd -ragged -offset indent -compact
|
|
@roff_tcache@Total number of thread cache bin size classes.
|
|
@roff_tcache@.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
|
|
.\"-----------------------------------------------------------------------------
|
|
.It Sy "arenas.purge (unsigned) -w"
|
|
.Bd -ragged -offset indent -compact
|
|
Purge unused dirty pages for the specified arena, or for all arenas if none is
|
|
specified.
|
|
.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_prof@.It Sy "prof.active (bool) rw"
|
|
@roff_prof@.Bd -ragged -offset indent -compact
|
|
@roff_prof@Control whether sampling is currently active.
|
|
@roff_prof@See the
|
|
@roff_prof@.Dq opt.prof_active
|
|
@roff_prof@option for additional information.
|
|
@roff_prof@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_prof@.It Sy "prof.dump (const char *) -w"
|
|
@roff_prof@.Bd -ragged -offset indent -compact
|
|
@roff_prof@Dump a memory profile to the specified file, or if NULL is specified,
|
|
@roff_prof@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@.Dq opt.prof_prefix
|
|
@roff_prof@option.
|
|
@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 opt.lg_prof_interval
|
|
@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 allocation requests served by small bins.
|
|
@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 objects returned to bins.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.arenas.<i>.small.nrequests (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>.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 served directly by
|
|
@roff_stats@the arena.
|
|
@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 served directly by
|
|
@roff_stats@the arena.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.arenas.<i>.large.nrequests (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>.bins.<j>.allocated (size_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Current number of bytes allocated by bin.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.arenas.<i>.bins.<j>.nmalloc (uint64_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Cumulative number of allocations served by bin.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.arenas.<i>.bins.<j>.ndalloc (uint64_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Cumulative number of allocations returned to bin.
|
|
@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>.nmalloc (uint64_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Cumulative number of allocation requests for this size class served
|
|
@roff_stats@directly by the arena.
|
|
@roff_stats@.Ed
|
|
.\"-----------------------------------------------------------------------------
|
|
@roff_stats@.It Sy "stats.arenas.<i>.lruns.<j>.ndalloc (uint64_t) r-"
|
|
@roff_stats@.Bd -ragged -offset indent -compact
|
|
@roff_stats@Cumulative number of deallocation requests for this size class
|
|
@roff_stats@served directly by the arena.
|
|
@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
|
|
Start by setting the
|
|
.Dq opt.abort
|
|
option, which 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 the program depends on the
|
|
@roff_fill@storage being filled with zero bytes.
|
|
@roff_fill@Try running it with the
|
|
@roff_fill@.Dq opt.zero
|
|
@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 opt.junk
|
|
@roff_fill@option may help provoke the problem.
|
|
@roff_fill@.Pp
|
|
This implementation does not provide much detail about the problems it detects,
|
|
because 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 opt.abort
|
|
option is set, most 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 cbopaque
|
|
pointer argument that is
|
|
.Dv NULL
|
|
unless overridden by the arguments in a call to
|
|
.Fn @jemalloc_prefix@malloc_stats_print ,
|
|
followed by a string pointer.
|
|
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
|
|
.Ss Standard API
|
|
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.
|
|
.Ss Non-standard API
|
|
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 @jemalloc_prefix@mallctl*
|
|
read/write processing.
|
|
.El
|
|
.Ss Experimental API
|
|
The
|
|
.Fn @jemalloc_prefix@allocm ,
|
|
.Fn @jemalloc_prefix@rallocm ,
|
|
.Fn @jemalloc_prefix@sallocm ,
|
|
and
|
|
.Fn @jemalloc_prefix@dallocm
|
|
functions return
|
|
.Dv ALLOCM_SUCCESS
|
|
on success; otherwise they return an error value.
|
|
The
|
|
.Fn @jemalloc_prefix@allocm
|
|
and
|
|
.Fn @jemalloc_prefix@rallocm
|
|
functions will fail if:
|
|
.Bl -tag -width ".Bq Er ALLOCM_ERR_OOM"
|
|
.It Bq Er ALLOCM_ERR_OOM
|
|
Out of memory.
|
|
Insufficient contiguous memory was available to service the allocation request.
|
|
The
|
|
.Fn @jemalloc_prefix@allocm
|
|
function additionally sets
|
|
.Fa *ptr
|
|
to
|
|
.Dv NULL ,
|
|
whereas the
|
|
.Fn @jemalloc_prefix@rallocm
|
|
function leaves
|
|
.Fa *ptr
|
|
unmodified.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn @jemalloc_prefix@rallocm
|
|
function will also fail if:
|
|
.Bl -tag -width ".Bq Er ALLOCM_ERR_NOT_MOVED"
|
|
.It Bq Er ALLOCM_ERR_NOT_MOVED
|
|
.Dv ALLOCM_NO_MOVE
|
|
was specified, but the reallocation request could not be serviced without
|
|
moving the object.
|
|
.El
|
|
.Sh ENVIRONMENT
|
|
The following environment variable affects the execution of the allocation
|
|
functions:
|
|
.Bl -tag -width ".Ev @jemalloc_cprefix@MALLOC_CONF"
|
|
.It Ev @jemalloc_cprefix@MALLOC_CONF
|
|
If the environment variable
|
|
.Ev @jemalloc_cprefix@MALLOC_CONF
|
|
is set, the characters it contains will be interpreted as options.
|
|
.El
|
|
.Sh EXAMPLES
|
|
To dump core whenever a problem occurs:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
ln -s 'abort:true' /etc/@jemalloc_prefix@malloc.conf
|
|
.Ed
|
|
.Pp
|
|
To specify in the source a chunk size that is 16 MiB:
|
|
.Bd -literal -offset indent
|
|
@jemalloc_prefix@malloc_conf = "lg_chunk:24";
|
|
.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 .
|