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
