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