diff options
Diffstat (limited to 'jemalloc/doc/jemalloc.3.in')
| -rw-r--r-- | jemalloc/doc/jemalloc.3.in | 1688 |
1 files changed, 0 insertions, 1688 deletions
diff --git a/jemalloc/doc/jemalloc.3.in b/jemalloc/doc/jemalloc.3.in deleted file mode 100644 index 6286664..0000000 --- a/jemalloc/doc/jemalloc.3.in +++ /dev/null @@ -1,1688 +0,0 @@ -.\" 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 October 24, 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" "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_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 . |