README.md
1# jemalloc-sys - Rust bindings to the `jemalloc` C library
2
3[![Travis-CI Status]][travis] [![Latest Version]][crates.io] [![docs]][docs.rs]
4
5> Note: the Rust allocator API is implemented for `jemalloc` in the
6> [`tikv-jemallocator`](https://crates.io/crates/tikv-jemallocator) crate.
7
8## Documentation
9
10* [Latest release (docs.rs)][docs.rs]
11
12`jemalloc` is a general purpose memory allocator, its documentation
13
14 can be found here:
15
16* [API documentation][jemalloc_docs]
17* [Wiki][jemalloc_wiki] (design documents, presentations, profiling, debugging, tuning, ...)
18
19[jemalloc_docs]: http://jemalloc.net/jemalloc.3.html
20[jemalloc_wiki]: https://github.com/jemalloc/jemalloc/wiki
21
22**Current jemalloc version**: 5.2.1.
23
24## Platform support
25
26See the platform support of the
27[`tikv-jemallocator`](https://crates.io/crates/tikv-jemallocator) crate.
28
29## Features
30
31Most features correspond to `jemalloc` features - the reference is
32[`jemalloc/INSTALL.md`][jemalloc_install].
33
34### Cargo features
35
36This crate provides following cargo feature flags:
37
38* `profiling` (configure `jemalloc` with `--enable-prof`): Enable heap profiling
39 and leak detection functionality. See jemalloc's "opt.prof" option
40 documentation for usage details. When enabled, there are several approaches to
41 backtracing, and the configure script chooses the first one in the following
42 list that appears to function correctly:
43
44 * `libunwind` (requires --enable-prof-libunwind)
45 * `libgcc` (unless --disable-prof-libgcc)
46 * `gcc intrinsics` (unless --disable-prof-gcc)
47
48* `stats` (configure `jemalloc` with `--enable-stats`): Enable statistics
49 gathering functionality. See the `jemalloc`'s "`opt.stats_print`" option
50 documentation for usage details.
51
52* `debug` (configure `jemalloc` with `--enable-debug`): Enable assertions and
53 validation code. This incurs a substantial performance hit, but is very useful
54 during application development.
55
56* `background_threads_runtime_support` (enabled by default): enables
57 background-threads run-time support when building `jemalloc-sys` on some POSIX
58 targets supported by `jemalloc`. Background threads are disabled at run-time
59 by default. This option allows dynamically enabling them at run-time.
60
61* `background_threads` (disabled by default): enables background threads by
62 default at run-time. When set to true, background threads are created on
63 demand (the number of background threads will be no more than the number of
64 CPUs or active arenas). Threads run periodically, and handle purging
65 asynchronously. When switching off, background threads are terminated
66 synchronously. Note that after `fork(2)` function, the state in the child
67 process will be disabled regardless the state in parent process. See
68 `stats.background_thread` for related stats. `opt.background_thread` can be
69 used to set the default option. The background thread is only available on
70 selected pthread-based platforms.
71
72* `unprefixed_malloc_on_supported_platforms`: when disabled, configure
73 `jemalloc` with `--with-jemalloc-prefix=_rjem_`. Enabling this causes symbols
74 like `malloc` to be emitted without a prefix, overriding the ones defined by
75 libc. This usually causes C and C++ code linked in the same program to use
76 `jemalloc` as well. On some platforms prefixes are always used because
77 unprefixing is known to cause segfaults due to allocator mismatches.
78
79* `disable_initial_exec_tls` (disabled by default): when enabled, jemalloc is
80 built with the `--disable-initial-exec-tls` option. It disables the
81 initial-exec TLS model for jemalloc's internal thread-local storage (on those
82 platforms that support explicit settings). This can allow jemalloc to be
83 dynamically loaded after program startup (e.g. using dlopen). If you encounter
84 the error `yourlib.so: cannot allocate memory in static TLS block`, you'll
85 likely want to enable this.
86
87* `disable_cache_oblivious` (disabled by default): when enabled, jemalloc is
88 built with the `--disable-cache-oblivious` option. In that case, all large
89 allocations are page-aligned as an implementation artifact. It may severely
90 harm CPU cache utilization. However, the cache-oblivious layout has a cost of
91 one extra page per large allocation which can be unfeasible for certain
92 applications.
93
94### Environment variables
95
96`jemalloc` options taking values are passed via environment variables using the
97schema `JEMALLOC_SYS_{KEY}=VALUE` where the `KEY` names correspond to the
98`./configure` options of `jemalloc` where the words are capitalized and the
99hyphens `-` are replaced with underscores `_`(see
100[`jemalloc/INSTALL.md`][jemalloc_install]):
101
102* `JEMALLOC_SYS_WITH_MALLOC_CONF=<malloc_conf>`: Embed `<malloc_conf>` as a
103 run-time options string that is processed prior to the `malloc_conf` global
104 variable, the `/etc/malloc.conf` symlink, and the `MALLOC_CONF` environment
105 variable (note: this variable might be prefixed as `_RJEM_MALLOC_CONF`). For
106 example, to change the default decay time for dirty pages to 30 seconds:
107
108 ```
109 JEMALLOC_SYS_WITH_MALLOC_CONF=dirty_decay_ms:30000
110 ```
111
112* `JEMALLOC_SYS_WITH_LG_PAGE=<lg-page>`: Specify the base 2 log of the allocator
113 page size, which must in turn be at least as large as the system page size. By
114 default the configure script determines the host's page size and sets the
115 allocator page size equal to the system page size, so this option need not be
116 specified unless the system page size may change between configuration and
117 execution, e.g. when cross compiling.
118
119* `JEMALLOC_SYS_WITH_LG_HUGEPAGE=<lg-hugepage>`: Specify the base 2 log of the
120 system huge page size. This option is useful when cross compiling, or when
121 overriding the default for systems that do not explicitly support huge pages.
122
123
124* `JEMALLOC_SYS_WITH_LG_QUANTUM=<lg-quantum>`: Specify the base 2 log of the
125 minimum allocation alignment. jemalloc needs to know the minimum alignment
126 that meets the following C standard requirement (quoted from the April 12,
127 2011 draft of the C11 standard):
128
129 > The pointer returned if the allocation succeeds is suitably aligned so that
130 > it may be assigned to a pointer to any type of object with a fundamental
131 > alignment requirement and then used to access such an object or an array of
132 > such objects in the space allocated [...]
133
134 This setting is architecture-specific, and although jemalloc includes known
135 safe values for the most commonly used modern architectures, there is a
136 wrinkle related to GNU libc (glibc) that may impact your choice of . On most
137 modern architectures, this mandates 16-byte alignment (=4), but the glibc
138 developers chose not to meet this requirement for performance reasons. An old
139 discussion can be found at https://sourceware.org/bugzilla/show_bug.cgi?id=206
140 . Unlike glibc, jemalloc does follow the C standard by default (caveat:
141 jemalloc technically cheats for size classes smaller than the quantum), but
142 the fact that Linux systems already work around this allocator noncompliance
143 means that it is generally safe in practice to let jemalloc's minimum
144 alignment follow glibc's lead. If you specify `JEMALLOC_SYS_WITH_LG_QUANTUM=3`
145 during configuration, jemalloc will provide additional size classes that are
146 not 16-byte-aligned (24, 40, and 56).
147
148* `JEMALLOC_SYS_WITH_LG_VADDR=<lg-vaddr>`: Specify the number of significant
149 virtual address bits. By default, the configure script attempts to detect
150 virtual address size on those platforms where it knows how, and picks a
151 default otherwise. This option may be useful when cross-compiling.
152
153[jemalloc_install]: https://github.com/jemalloc/jemalloc/blob/dev/INSTALL.md#advanced-configuration
154
155## License
156
157This project is licensed under either of
158
159 * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
160 http://www.apache.org/licenses/LICENSE-2.0)
161 * MIT license ([LICENSE-MIT](LICENSE-MIT) or
162 http://opensource.org/licenses/MIT)
163
164at your option.
165
166## Contribution
167
168Unless you explicitly state otherwise, any contribution intentionally submitted
169for inclusion in `tikv-jemalloc-sys` by you, as defined in the Apache-2.0 license,
170shall be dual licensed as above, without any additional terms or conditions.
171
172[travis]: https://travis-ci.com/tikv/jemallocator
173[Travis-CI Status]: https://travis-ci.com/tikv/jemallocator.svg?branch=master
174[Latest Version]: https://img.shields.io/crates/v/tikv-jemallocator.svg
175[crates.io]: https://crates.io/crates/tikv-jemallocator
176[docs]: https://docs.rs/tikv-jemallocator/badge.svg
177[docs.rs]: https://docs.rs/tikv-jemallocator/
178
