| .\" 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 April 2, 2010 |
| .Dt JEMALLOC 3 |
| .Os |
| .Sh NAME |
| .Nm @jemalloc_prefix@malloc , |
| .Nm @jemalloc_prefix@calloc , |
| .Nm @jemalloc_prefix@posix_memalign , |
| .Nm @jemalloc_prefix@realloc , |
| .Nm @jemalloc_prefix@free , |
| .Nm @jemalloc_prefix@malloc_usable_size , |
| .Nm @jemalloc_prefix@malloc_stats_print , |
| .Nm @jemalloc_prefix@mallctl , |
| .Nm @jemalloc_prefix@mallctlnametomib , |
| .Nm @jemalloc_prefix@mallctlbymib |
| .Nd general purpose memory allocation functions |
| .Sh LIBRARY |
| .Sy libjemalloc@install_suffix@ |
| .Sh SYNOPSIS |
| .In stdlib.h |
| .In jemalloc/jemalloc@install_suffix@.h |
| .Ft void * |
| .Fn @jemalloc_prefix@malloc "size_t size" |
| .Ft void * |
| .Fn @jemalloc_prefix@calloc "size_t number" "size_t size" |
| .Ft int |
| .Fn @jemalloc_prefix@posix_memalign "void **ptr" "size_t alignment" "size_t size" |
| .Ft void * |
| .Fn @jemalloc_prefix@realloc "void *ptr" "size_t size" |
| .Ft void |
| .Fn @jemalloc_prefix@free "void *ptr" |
| .Ft size_t |
| .Fn @jemalloc_prefix@malloc_usable_size "const void *ptr" |
| .Ft void |
| .Fn @jemalloc_prefix@malloc_stats_print "void (*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_options ; |
| .Ft void |
| .Fn \*(lp*@jemalloc_prefix@malloc_message\*(rp "void *cbopaque" "const char *s" |
| .Sh DESCRIPTION |
| The |
| .Fn @jemalloc_prefix@malloc |
| function allocates |
| .Fa size |
| bytes of uninitialized memory. |
| The allocated space is suitably aligned |
| @roff_tiny@(after possible pointer coercion) |
| for storage of any type of object. |
| .Pp |
| The |
| .Fn @jemalloc_prefix@calloc |
| function allocates space for |
| .Fa number |
| objects, |
| each |
| .Fa size |
| bytes in length. |
| The result is identical to calling |
| .Fn @jemalloc_prefix@malloc |
| with an argument of |
| .Dq "number * size" , |
| with the exception that the allocated memory is explicitly initialized |
| to zero bytes. |
| .Pp |
| The |
| .Fn @jemalloc_prefix@posix_memalign |
| function allocates |
| .Fa size |
| bytes of memory such that the allocation's base address is an even multiple of |
| .Fa alignment , |
| and returns the allocation in the value pointed to by |
| .Fa ptr . |
| The requested |
| .Fa alignment |
| must be a power of 2 at least as large as |
| .Fn sizeof "void *" . |
| .Pp |
| The |
| .Fn @jemalloc_prefix@realloc |
| function changes the size of the previously allocated memory referenced by |
| .Fa ptr |
| to |
| .Fa size |
| bytes. |
| The contents of the memory are unchanged up to the lesser of the new and |
| old sizes. |
| If the new size is larger, |
| the contents of the newly allocated portion of the memory are undefined. |
| Upon success, the memory referenced by |
| .Fa ptr |
| is freed and a pointer to the newly allocated memory is returned. |
| Note that |
| .Fn @jemalloc_prefix@realloc |
| may move the memory allocation, resulting in a different return value than |
| .Fa ptr . |
| If |
| .Fa ptr |
| is |
| .Dv NULL , |
| the |
| .Fn @jemalloc_prefix@realloc |
| function behaves identically to |
| .Fn @jemalloc_prefix@malloc |
| for the specified size. |
| .Pp |
| The |
| .Fn @jemalloc_prefix@free |
| function causes the allocated memory referenced by |
| .Fa ptr |
| to be made available for future allocations. |
| If |
| .Fa ptr |
| is |
| .Dv NULL , |
| no action occurs. |
| .Pp |
| The |
| .Fn @jemalloc_prefix@malloc_usable_size |
| function returns the usable size of the allocation pointed to by |
| .Fa ptr . |
| The return value may be larger than the size that was requested during |
| allocation. |
| The |
| .Fn @jemalloc_prefix@malloc_usable_size |
| function is not a mechanism for in-place |
| .Fn @jemalloc_prefix@realloc ; |
| rather it is provided solely as a tool for introspection purposes. |
| Any discrepancy between the requested allocation size and the size reported by |
| .Fn @jemalloc_prefix@malloc_usable_size |
| should not be depended on, since such behavior is entirely |
| implementation-dependent. |
| .Pp |
| The |
| .Fn @jemalloc_prefix@malloc_stats_print |
| function writes human-readable summary statistics via the |
| .Fa 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 |
| .Sh TUNING |
| Once, when the first call is made to one of these memory allocation |
| routines, various flags will be set or reset, which affects the |
| workings of this allocator implementation. |
| .Pp |
| The |
| .Dq name |
| of the file referenced by the symbolic link named |
| .Pa /etc/jemalloc.conf , |
| the value of the environment variable |
| .Ev JEMALLOC_OPTIONS , |
| and the string pointed to by the global variable |
| .Va @jemalloc_prefix@malloc_options |
| will be interpreted, in that order, from left to right as flags. |
| .Pp |
| Each flag is a single letter, optionally prefixed by a non-negative base 10 |
| integer repetition count. |
| For example, |
| .Dq 3N |
| is equivalent to |
| .Dq NNN . |
| Some flags control parameter magnitudes, where uppercase increases the |
| magnitude, and lowercase decreases the magnitude. |
| Other flags control boolean parameters, where uppercase indicates that a |
| behavior is set, or on, and lowercase means that a behavior is not set, or off. |
| .Bl -tag -width indent |
| .It A |
| All warnings (except for the warning about unknown |
| flags being set) become fatal. |
| The process will call |
| .Xr abort 3 |
| in these cases. |
| @roff_prof@.It B |
| @roff_prof@Double/halve the maximum backtrace depth when profiling memory |
| @roff_prof@allocation activity. |
| @roff_prof@The default is 4. |
| .It C |
| Double/halve the size of the maximum size class that is a multiple of the |
| cacheline size (64). |
| Above this size, subpage spacing (256 bytes) is used for size classes. |
| The default value is 512 bytes. |
| .It D |
| Halve/double the per-arena minimum ratio of active to dirty pages. |
| Some dirty unused pages may be allowed to accumulate, within the limit set by |
| the ratio (or one chunk worth of dirty pages, whichever is greater), before |
| informing the kernel about some of those pages via |
| .Xr madvise 2 . |
| This provides the kernel with sufficient information to recycle dirty pages if |
| physical memory becomes scarce and the pages remain unused. |
| The default minimum ratio is 32:1; |
| .Ev JEMALLOC_OPTIONS=6D |
| will disable dirty page purging. |
| @roff_prof@.It E |
| @roff_prof@Activate/deactivate profiling. |
| @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 F |
| @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@.It F |
| @roff_prof@Profile memory allocation activity, and use an |
| @roff_prof@.Xr atexit 3 |
| @roff_prof@function to dump final memory usage to a file named according to |
| @roff_prof@the pattern |
| @roff_prof@.Pa <prefix>.<pid>.<seq>.f.heap , |
| @roff_prof@where |
| @roff_prof@.Pa <prefix> |
| @roff_prof@is controlled by the |
| @roff_prof@JEMALLOC_PROF_PREFIX |
| @roff_prof@environment variable. |
| @roff_prof@See the |
| @roff_prof@.Dq B |
| @roff_prof@option for backtrace depth control. |
| @roff_prof@See the |
| @roff_prof@.Dq E |
| @roff_prof@option for on-the-fly activation/deactivation. |
| @roff_prof@See the |
| @roff_prof@.Dq S |
| @roff_prof@option for probabilistic sampling control. |
| @roff_prof@See the |
| @roff_prof@.Dq I |
| @roff_prof@option for information on interval-triggered profile dumping, and the |
| @roff_prof@.Dq U |
| @roff_prof@option for information on high-water-triggered profile dumping. |
| @roff_prof@Profile output is compatible with the included pprof Perl script, |
| @roff_prof@which originates from the google-perftools package |
| @roff_prof@(http://code.google.com/p/google-perftools/). |
| @roff_tcache@.It G |
| @roff_tcache@Double/halve the approximate interval (counted in terms of |
| @roff_tcache@thread-specific cache allocation/deallocation events) between full |
| @roff_tcache@thread-specific cache garbage collection sweeps. |
| @roff_tcache@Garbage collection is actually performed incrementally, one size |
| @roff_tcache@class at a time, in order to avoid large collection pauses. |
| @roff_tcache@The default sweep interval is 8192; |
| @roff_tcache@.Ev JEMALLOC_OPTIONS=14g |
| @roff_tcache@will disable garbage collection. |
| @roff_tcache@.It H |
| @roff_tcache@Enable/disable thread-specific caching. |
| @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 G |
| @roff_tcache@and |
| @roff_tcache@.Dq M |
| @roff_tcache@options for related tuning information. |
| @roff_tcache@This option is enabled by default. |
| @roff_prof@.It I |
| @roff_prof@Double/halve the average interval between memory profile dumps, as |
| @roff_prof@measured in bytes of allocation activity. |
| @roff_prof@The actual interval between dumps may be sporadic because |
| @roff_prof@decentralized allocation counters are used to avoid synchronization |
| @roff_prof@bottlenecks. |
| @roff_prof@Profiles are dumped to files named according to the pattern |
| @roff_prof@.Pa <prefix>.<pid>.<seq>.i<iseq>.heap , |
| @roff_prof@where |
| @roff_prof@.Pa <prefix> |
| @roff_prof@is controlled by the |
| @roff_prof@JEMALLOC_PROF_PREFIX |
| @roff_prof@environment variable. |
| @roff_prof@The default average interval is 1 GiB; |
| @roff_prof@.Ev JEMALLOC_OPTIONS=31i |
| @roff_prof@will disable interval-triggered profile dumping. |
| @roff_fill@.It J |
| @roff_fill@Each byte of new memory allocated by |
| @roff_fill@.Fn @jemalloc_prefix@malloc |
| @roff_fill@or |
| @roff_fill@.Fn @jemalloc_prefix@realloc |
| @roff_fill@will be initialized to 0xa5. |
| @roff_fill@All memory returned by |
| @roff_fill@.Fn @jemalloc_prefix@free |
| @roff_fill@or |
| @roff_fill@.Fn @jemalloc_prefix@realloc |
| @roff_fill@will be initialized to 0x5a. |
| @roff_fill@This is intended for debugging and will impact performance |
| @roff_fill@negatively. |
| .It K |
| Double/halve the virtual memory chunk size. |
| The default chunk size is 4 MiB. |
| @roff_prof@.It L |
| @roff_prof@Use an |
| @roff_prof@.Xr atexit 3 |
| @roff_prof@function to report memory leaks. |
| @roff_prof@See the |
| @roff_prof@.Dq B |
| @roff_prof@option for backtrace depth control. |
| @roff_prof@See the |
| @roff_prof@.Dq F option for information on analyzing heap profile output. |
| @roff_prof@This option is disabled by default. |
| @roff_tcache@.It M |
| @roff_tcache@Double/halve the maximum size class to 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. |
| .It N |
| Double/halve the number of arenas. |
| The default number of arenas is four times the number of CPUs, or one if there |
| is a single CPU. |
| @roff_swap@.It O |
| @roff_swap@Over-commit memory as a side effect of using anonymous |
| @roff_swap@.Xr mmap 2 |
| @roff_swap@@roff_dss@ and |
| @roff_swap@@roff_dss@.Xr sbrk 2 |
| @roff_swap@for virtual memory allocation. |
| @roff_swap@In order for overcommit to be disabled, the |
| @roff_swap@.Dq swap.fds |
| @roff_swap@mallctl must have been successfully written to. |
| @roff_swap@This option is enabled by default. |
| .It P |
| The |
| .Fn @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. |
| .It Q |
| Double/halve the size of the maximum size class that is a multiple of the |
| quantum (8 or 16 bytes, depending on architecture). |
| Above this size, cacheline spacing is used for size classes. |
| The default value is 128 bytes. |
| @roff_prof@.It S |
| @roff_prof@Double/halve the average interval 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 one (i.e. all allocations are |
| @roff_prof@sampled). |
| @roff_prof@.It U |
| @roff_prof@Trigger a memory profile dump every time the total virtual memory |
| @roff_prof@exceeds the previous maximum. |
| @roff_prof@Profiles are dumped to files named according to the pattern |
| @roff_prof@.Pa <prefix>.<pid>.<seq>.u<useq>.heap , |
| @roff_prof@where |
| @roff_prof@.Pa <prefix> |
| @roff_prof@is controlled by the |
| @roff_prof@JEMALLOC_PROF_PREFIX |
| @roff_prof@environment variable. |
| @roff_prof@This option is disabled by default. |
| @roff_sysv@.It V |
| @roff_sysv@Attempting to allocate zero bytes will return a |
| @roff_sysv@.Dv NULL |
| @roff_sysv@pointer instead of a valid pointer. |
| @roff_sysv@(The default behavior is to make a minimal allocation and return a |
| @roff_sysv@pointer to it.) |
| @roff_sysv@This option is provided for System V compatibility. |
| @roff_sysv@@roff_xmalloc@This option is incompatible with the |
| @roff_sysv@@roff_xmalloc@.Dq X |
| @roff_sysv@@roff_xmalloc@option. |
| @roff_xmalloc@.It X |
| @roff_xmalloc@Rather than return failure for any allocation function, display a |
| @roff_xmalloc@diagnostic message on |
| @roff_xmalloc@.Dv STDERR_FILENO |
| @roff_xmalloc@and cause the program to drop core (using |
| @roff_xmalloc@.Xr abort 3 ) . |
| @roff_xmalloc@This option should be set at compile time by including the |
| @roff_xmalloc@following in the source code: |
| @roff_xmalloc@.Bd -literal -offset indent |
| @roff_xmalloc@@jemalloc_prefix@malloc_options = "X"; |
| @roff_xmalloc@.Ed |
| @roff_fill@.It Z |
| @roff_fill@Each byte of new memory allocated by |
| @roff_fill@.Fn @jemalloc_prefix@malloc |
| @roff_fill@or |
| @roff_fill@.Fn @jemalloc_prefix@realloc |
| @roff_fill@will be initialized to 0. |
| @roff_fill@Note that this initialization only happens once for each byte, so |
| @roff_fill@.Fn @jemalloc_prefix@realloc |
| @roff_fill@calls do not zero memory that was previously allocated. |
| @roff_fill@This is intended for debugging and will impact performance |
| @roff_fill@negatively. |
| .El |
| .Pp |
| @roff_fill@The |
| @roff_fill@.Dq J |
| @roff_fill@and |
| @roff_fill@.Dq Z |
| @roff_fill@options are intended for testing and debugging. |
| @roff_fill@An application which changes its behavior when these options are used |
| @roff_fill@is flawed. |
| .Sh IMPLEMENTATION NOTES |
| @roff_dss@Traditionally, allocators have used |
| @roff_dss@.Xr sbrk 2 |
| @roff_dss@to obtain memory, which is suboptimal for several reasons, including |
| @roff_dss@race conditions, increased fragmentation, and artificial limitations |
| @roff_dss@on maximum usable memory. |
| @roff_dss@This allocator uses both |
| @roff_dss@.Xr sbrk 2 |
| @roff_dss@and |
| @roff_dss@.Xr mmap 2 , |
| @roff_dss@in that order of preference. |
| .Pp |
| This allocator uses multiple arenas in order to reduce lock contention for |
| threaded programs on multi-processor systems. |
| This works well with regard to threading scalability, but incurs some costs. |
| There is a small fixed per-arena overhead, and additionally, arenas manage |
| memory completely independently of each other, which means a small fixed |
| increase in overall memory fragmentation. |
| These overheads are not generally an issue, given the number of arenas normally |
| used. |
| Note that using substantially more arenas than the default is not likely to |
| improve performance, mainly due to reduced cache performance. |
| However, it may make sense to reduce the number of arenas if an application |
| does not make much use of the allocation functions. |
| .Pp |
| @roff_tcache@In addition to multiple arenas, this allocator supports |
| @roff_tcache@thread-specific caching for small objects, in order to make it |
| @roff_tcache@possible to completely avoid synchronization for most small |
| @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 bitmap that tracks which regions are in use. |
| @roff_tiny@Allocation requests that are no more than half the quantum (8 or 16, |
| @roff_tiny@depending on architecture) are rounded up to the nearest power of |
| @roff_tiny@two. |
| Allocation requests that are |
| @roff_tiny@more than half the quantum, but |
| no more than the minimum cacheline-multiple size class (see the |
| .Dq Q |
| option) are rounded up to the nearest multiple of the |
| @roff_tiny@quantum. |
| @roff_no_tiny@quantum (8 or 16, depending on architecture). |
| Allocation requests that are more than the minimum cacheline-multiple size |
| class, but no more than the minimum subpage-multiple size class (see the |
| .Dq C |
| option) are rounded up to the nearest multiple of the cacheline size (64). |
| Allocation requests that are more than the minimum subpage-multiple size class, |
| but no more than the maximum subpage-multiple size class are rounded up to the |
| nearest multiple of the subpage size (256). |
| Allocation requests that are more than the maximum subpage-multiple size class, |
| but small enough to fit in an arena-managed chunk (see the |
| .Dq K |
| option), are rounded up to the nearest run size. |
| Allocation requests that are too large to fit in an arena-managed chunk are |
| rounded up to the nearest multiple of the chunk size. |
| .Pp |
| Allocations are packed tightly together, which can be an issue for |
| multi-threaded applications. |
| If you need to assure that allocations do not suffer from cacheline sharing, |
| round your allocation requests up to the nearest multiple of the cacheline |
| size. |
| .Sh MALLCTL NAMESPACE |
| The following names are defined in the namespace accessible via the |
| .Fn @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. |
| .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 |
| .\"----------------------------------------------------------------------------- |
| @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 |
| .\"----------------------------------------------------------------------------- |
| .It Sy "config.debug (bool) r-" |
| .Bd -ragged -offset indent -compact |
| --enable-debug was specified during build configuration. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "config.dss (bool) r-" |
| .Bd -ragged -offset indent -compact |
| --enable-dss was specified during build configuration. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "config.dynamic_page_shift (bool) r-" |
| .Bd -ragged -offset indent -compact |
| --enable-dynamic-page-shift was specified during build configuration. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "config.fill (bool) r-" |
| .Bd -ragged -offset indent -compact |
| --enable-fill was specified during build configuration. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "config.lazy_lock (bool) r-" |
| .Bd -ragged -offset indent -compact |
| --enable-lazy-lock was specified during build configuration. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "config.prof (bool) r-" |
| .Bd -ragged -offset indent -compact |
| --enable-prof was specified during build configuration. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "config.prof_libgcc (bool) r-" |
| .Bd -ragged -offset indent -compact |
| --disable-prof-libgcc was not specified during build configuration. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "config.prof_libunwind (bool) r-" |
| .Bd -ragged -offset indent -compact |
| --enable-prof-libunwind was specified during build configuration. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "config.stats (bool) r-" |
| .Bd -ragged -offset indent -compact |
| --enable-stats was specified during build configuration. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "config.swap (bool) r-" |
| .Bd -ragged -offset indent -compact |
| --enable-swap was specified during build configuration. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "config.sysv (bool) r-" |
| .Bd -ragged -offset indent -compact |
| --enable-sysv was specified during build configuration. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "config.tcache (bool) r-" |
| .Bd -ragged -offset indent -compact |
| --disable-tcache was not specified during build configuration. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "config.tiny (bool) r-" |
| .Bd -ragged -offset indent -compact |
| --disable-tiny was not specified during build configuration. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "config.tls (bool) r-" |
| .Bd -ragged -offset indent -compact |
| --disable-tls was not specified during build configuration. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "config.xmalloc (bool) r-" |
| .Bd -ragged -offset indent -compact |
| --enable-xmalloc was specified during build configuration. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "opt.abort (bool) r-" |
| .Bd -ragged -offset indent -compact |
| See the |
| .Dq A |
| option. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_fill@.It Sy "opt.junk (bool) r-" |
| @roff_fill@.Bd -ragged -offset indent -compact |
| @roff_fill@See the |
| @roff_fill@.Dq J |
| @roff_fill@option. |
| @roff_fill@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_fill@.It Sy "opt.zero (bool) r-" |
| @roff_fill@.Bd -ragged -offset indent -compact |
| @roff_fill@See the |
| @roff_fill@.Dq Z |
| @roff_fill@option. |
| @roff_fill@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_xmalloc@.It Sy "opt.xmalloc (bool) r-" |
| @roff_xmalloc@.Bd -ragged -offset indent -compact |
| @roff_xmalloc@See the |
| @roff_xmalloc@.Dq X |
| @roff_xmalloc@option. |
| @roff_xmalloc@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_tcache@.It Sy "opt.tcache (bool) r-" |
| @roff_tcache@.Bd -ragged -offset indent -compact |
| @roff_tcache@See the |
| @roff_tcache@.Dq H |
| @roff_tcache@option. |
| @roff_tcache@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_tcache@.It Sy "opt.lg_tcache_gc_sweep (ssize_t) r-" |
| @roff_tcache@.Bd -ragged -offset indent -compact |
| @roff_tcache@See the |
| @roff_tcache@.Dq G |
| @roff_tcache@option. |
| @roff_tcache@.Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "opt.stats_print (bool) r-" |
| .Bd -ragged -offset indent -compact |
| See the |
| .Dq P |
| option. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_prof@.It Sy "opt.prof (bool) r-" |
| @roff_prof@.Bd -ragged -offset indent -compact |
| @roff_prof@See the |
| @roff_prof@.Dq F |
| @roff_prof@option. |
| @roff_prof@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_prof@.It Sy "opt.lg_prof_bt_max (size_t) r-" |
| @roff_prof@.Bd -ragged -offset indent -compact |
| @roff_prof@See the |
| @roff_prof@.Dq B |
| @roff_prof@option. |
| @roff_prof@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_prof@.It Sy "opt.lg_prof_interval (ssize_t) r-" |
| @roff_prof@.Bd -ragged -offset indent -compact |
| @roff_prof@See the |
| @roff_prof@.Dq I |
| @roff_prof@option. |
| @roff_prof@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_prof@.It Sy "opt.prof_udump (bool) r-" |
| @roff_prof@.Bd -ragged -offset indent -compact |
| @roff_prof@See the |
| @roff_prof@.Dq U |
| @roff_prof@option. |
| @roff_prof@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_prof@.It Sy "opt.prof_leak (bool) r-" |
| @roff_prof@.Bd -ragged -offset indent -compact |
| @roff_prof@See the |
| @roff_prof@.Dq L |
| @roff_prof@option. |
| @roff_prof@.Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "opt.lg_qspace_max (size_t) r-" |
| .Bd -ragged -offset indent -compact |
| See the |
| .Dq Q |
| option. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "opt.lg_cspace_max (size_t) r-" |
| .Bd -ragged -offset indent -compact |
| See the |
| .Dq C |
| option. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "opt.lg_dirty_mult (ssize_t) r-" |
| .Bd -ragged -offset indent -compact |
| See the |
| .Dq D |
| option. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "opt.lg_chunk (size_t) r-" |
| .Bd -ragged -offset indent -compact |
| See the |
| .Dq K |
| option. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "opt.overcommit (bool) r-" |
| .Bd -ragged -offset indent -compact |
| See the |
| .Dq O |
| option. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.narenas (unsigned) r-" |
| .Bd -ragged -offset indent -compact |
| Maximum number of arenas. |
| See the |
| .Dq N |
| option. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.initialized (bool *) r-" |
| .Bd -ragged -offset indent -compact |
| An array of arenas.narenas booleans. |
| Each boolean indicates whether the corresponding arena is initialized. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.quantum (size_t) r-" |
| .Bd -ragged -offset indent -compact |
| Quantum size. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.cacheline (size_t) r-" |
| .Bd -ragged -offset indent -compact |
| Assumed cacheline size. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.subpage (size_t) r-" |
| .Bd -ragged -offset indent -compact |
| Subpage size class interval. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.pagesize (size_t) r-" |
| .Bd -ragged -offset indent -compact |
| Page size. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.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 |
| .\"----------------------------------------------------------------------------- |
| @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 E |
| @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@JEMALLOC_PROF_PREFIX |
| @roff_prof@environment variable. |
| @roff_prof@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_prof@.It Sy "prof.interval (uint64_t) r-" |
| @roff_prof@.Bd -ragged -offset indent -compact |
| @roff_prof@Average number of bytes allocated between inverval-based profile |
| @roff_prof@dumps. |
| @roff_prof@See the |
| @roff_prof@.Dq I |
| @roff_prof@option for additional information. |
| @roff_prof@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.allocated (size_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Total number of bytes allocated by the application. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.active (size_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Total number of bytes in active pages allocated by the application. |
| @roff_stats@This is a multiple of the page size, and greater than or equal to |
| @roff_stats@.Dq stats.allocated . |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.mapped (size_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Total number of bytes in chunks mapped on behalf of the application. |
| @roff_stats@This is a multiple of the chunk size, and is at least as large as |
| @roff_stats@.Dq stats.active . |
| @roff_stats@@roff_swap@This does not include inactive chunks backed by swap |
| @roff_stats@@roff_swap@files. |
| @roff_stats@@roff_dss@This does not include inactive chunks embedded in the DSS. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.chunks.current (size_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Total number of chunks actively mapped on behalf of the application. |
| @roff_stats@@roff_swap@This does not include inactive chunks backed by swap |
| @roff_stats@@roff_swap@files. |
| @roff_stats@@roff_dss@This does not include inactive chunks embedded in the DSS. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.chunks.total (uint64_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Cumulative number of chunks allocated. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.chunks.high (size_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Maximum number of active chunks at any time thus far. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.huge.allocated (size_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Number of bytes currently allocated by huge objects. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.huge.nmalloc (uint64_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Cumulative number of huge allocation requests. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.huge.ndalloc (uint64_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Cumulative number of huge deallocation requests. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "stats.arenas.<i>.pactive (size_t) r-" |
| .Bd -ragged -offset indent -compact |
| Number of pages in active runs. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "stats.arenas.<i>.pdirty (size_t) r-" |
| .Bd -ragged -offset indent -compact |
| Number of pages within unused runs that are potentially dirty, and for which |
| .Fn madvise "..." "MADV_DONTNEED" |
| has not been called. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.arenas.<i>.mapped (size_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Number of mapped bytes. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.arenas.<i>.npurge (uint64_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Number of dirty page purge sweeps performed. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.arenas.<i>.nmadvise (uint64_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Number of |
| @roff_stats@.Fn madvise "..." "MADV_DONTNEED" |
| @roff_stats@calls made to purge dirty pages. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.arenas.<i>.npurged (uint64_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Number of pages purged. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.arenas.<i>.small.allocated (size_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Number of bytes currently allocated by small objects. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.arenas.<i>.small.nmalloc (uint64_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Cumulative number of 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 |
| The first thing to do is to set the |
| .Dq A |
| option. |
| This option forces a coredump (if possible) at the first sign of trouble, |
| rather than the normal policy of trying to continue if at all possible. |
| .Pp |
| It is probably also a good idea to recompile the program with suitable |
| options and symbols for debugger support. |
| .Pp |
| @roff_fill@If the program starts to give unusual results, coredump or generally |
| @roff_fill@behave differently without emitting any of the messages mentioned in |
| @roff_fill@the next section, it is likely because it depends on the storage |
| @roff_fill@being filled with zero bytes. |
| @roff_fill@Try running it with the |
| @roff_fill@.Dq Z |
| @roff_fill@option set; |
| @roff_fill@if that improves the situation, this diagnosis has been confirmed. |
| @roff_fill@If the program still misbehaves, |
| @roff_fill@the likely problem is accessing memory outside the allocated area. |
| @roff_fill@.Pp |
| @roff_fill@Alternatively, if the symptoms are not easy to reproduce, setting the |
| @roff_fill@.Dq J |
| @roff_fill@option may help provoke the problem. |
| @roff_fill@.Pp |
| Unfortunately this implementation does not provide much detail about |
| the problems it detects; the performance impact for storing such information |
| would be prohibitive. |
| There are a number of allocator implementations available on the Internet |
| which focus on detecting and pinpointing problems by trading performance for |
| extra sanity checks and detailed diagnostics. |
| .Sh DIAGNOSTIC MESSAGES |
| If any of the memory allocation/deallocation functions detect an error or |
| warning condition, a message will be printed to file descriptor |
| .Dv STDERR_FILENO . |
| Errors will result in the process dumping core. |
| If the |
| .Dq A |
| option is set, all warnings are treated as errors. |
| .Pp |
| The |
| .Va @jemalloc_prefix@malloc_message |
| variable allows the programmer to override the function which emits the text |
| strings forming the errors and warnings if for some reason the |
| .Dv STDERR_FILENO |
| file descriptor is not suitable for this. |
| .Va @jemalloc_prefix@malloc_message |
| takes the |
| .Fa 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 |
| The |
| .Fn @jemalloc_prefix@malloc |
| and |
| .Fn @jemalloc_prefix@calloc |
| functions return a pointer to the allocated memory if successful; otherwise |
| a |
| .Dv NULL |
| pointer is returned and |
| .Va errno |
| is set to |
| .Er ENOMEM . |
| .Pp |
| The |
| .Fn @jemalloc_prefix@posix_memalign |
| function returns the value 0 if successful; otherwise it returns an error value. |
| The |
| .Fn @jemalloc_prefix@posix_memalign |
| function will fail if: |
| .Bl -tag -width Er |
| .It Bq Er EINVAL |
| The |
| .Fa alignment |
| parameter is not a power of 2 at least as large as |
| .Fn sizeof "void *" . |
| .It Bq Er ENOMEM |
| Memory allocation error. |
| .El |
| .Pp |
| The |
| .Fn @jemalloc_prefix@realloc |
| function returns a pointer, possibly identical to |
| .Fa ptr , |
| to the allocated memory |
| if successful; otherwise a |
| .Dv NULL |
| pointer is returned, and |
| .Va errno |
| is set to |
| .Er ENOMEM |
| if the error was the result of an allocation failure. |
| The |
| .Fn @jemalloc_prefix@realloc |
| function always leaves the original buffer intact |
| when an error occurs. |
| .Pp |
| The |
| .Fn @jemalloc_prefix@free |
| function returns no value. |
| .Pp |
| The |
| .Fn @jemalloc_prefix@malloc_usable_size |
| function returns the usable size of the allocation pointed to by |
| .Fa ptr . |
| .Pp |
| The |
| .Fn @jemalloc_prefix@mallctl , |
| .Fn @jemalloc_prefix@mallctlnametomib , |
| and |
| .Fn @jemalloc_prefix@mallctlbymib |
| functions return 0 on success; otherwise they return an error value. |
| The functions will fail if: |
| .Bl -tag -width Er |
| .It Bq Er EINVAL |
| .Fa newp |
| is |
| .Dv non-NULL , |
| and |
| .Fa newlen |
| is too large or too small. |
| Alternatively, |
| .Fa *oldlenp |
| is too large or too small; in this case as much data as possible are read |
| despite the error. |
| .It Bq Er ENOMEM |
| .Fa *oldlenp |
| is too short to hold the requested value. |
| .It Bq Er ENOENT |
| .Fa name |
| or |
| .Fa mib |
| specifies an unknown/invalid value. |
| .It Bq Er EPERM |
| Attempt to read or write void value, or attempt to write read-only value. |
| .It Bq Er EAGAIN |
| A memory allocation failure occurred. |
| .It Bq Er EFAULT |
| An interface with side effects failed in some way not directly related to |
| .Fn @jemalloc_prefix@mallctl* |
| read/write processing. |
| .El |
| .Sh ENVIRONMENT |
| The following environment variables affect the execution of the allocation |
| functions: |
| @roff_prof@.Bl -tag -width ".Ev JEMALLOC_PROF_PREFIX" |
| @roff_no_prof@.Bl -tag -width ".Ev JEMALLOC_OPTIONS" |
| .It Ev JEMALLOC_OPTIONS |
| If the environment variable |
| .Ev JEMALLOC_OPTIONS |
| is set, the characters it contains will be interpreted as flags to the |
| allocation functions. |
| @roff_prof@.It Ev JEMALLOC_PROF_PREFIX |
| @roff_prof@If the environment variable |
| @roff_prof@.Ev JEMALLOC_PROF_PREFIX |
| @roff_prof@is set, use it as the filename prefix for profile dumps; otherwise |
| @roff_prof@use |
| @roff_prof@.Pa jeprof |
| @roff_prof@as the prefix. |
| .El |
| .Sh EXAMPLES |
| To dump core whenever a problem occurs: |
| .Pp |
| .Bd -literal -offset indent |
| ln -s 'A' /etc/jemalloc.conf |
| .Ed |
| .Pp |
| To specify in the source a chunk size that is twice the default: |
| .Bd -literal -offset indent |
| @jemalloc_prefix@malloc_options = "K"; |
| .Ed |
| .Sh SEE ALSO |
| .Xr madvise 2 , |
| .Xr mmap 2 , |
| @roff_dss@.Xr sbrk 2 , |
| .Xr alloca 3 , |
| .Xr atexit 3 , |
| .Xr getpagesize 3 |
| .Sh STANDARDS |
| The |
| .Fn @jemalloc_prefix@malloc , |
| .Fn @jemalloc_prefix@calloc , |
| .Fn @jemalloc_prefix@realloc |
| and |
| .Fn @jemalloc_prefix@free |
| functions conform to |
| .St -isoC . |
| .Pp |
| The |
| .Fn @jemalloc_prefix@posix_memalign |
| function conforms to |
| .St -p1003.1-2001 . |