README.md
1# tikv-jemallocator
2
3[![ci]][github actions] [![Latest Version]][crates.io] [![docs]][docs.rs]
4
5This project is the successor of [jemallocator](https://github.com/gnzlbg/jemallocator).
6
7The project is also published as `jemallocator` for historical reasons. The two crates are the same except names. For new projects, it's recommended to use `tikv-xxx` versions instead.
8
9> Links against `jemalloc` and provides a `Jemalloc` unit type that implements
10> the allocator APIs and can be set as the `#[global_allocator]`
11
12## Overview
13
14The `jemalloc` support ecosystem consists of the following crates:
15
16* `tikv-jemalloc-sys`: builds and links against `jemalloc` exposing raw C bindings to it.
17* `tikv-jemallocator`: provides the `Jemalloc` type which implements the
18 `GlobalAlloc` and `Alloc` traits.
19* `tikv-jemalloc-ctl`: high-level wrapper over `jemalloc`'s control and introspection
20 APIs (the `mallctl*()` family of functions and the _MALLCTL NAMESPACE_)'
21
22## Documentation
23
24* [Latest release (docs.rs)][docs.rs]
25
26To use `tikv-jemallocator` add it as a dependency:
27
28```toml
29# Cargo.toml
30[dependencies]
31
32[target.'cfg(not(target_env = "msvc"))'.dependencies]
33tikv-jemallocator = "0.5"
34```
35
36To set `tikv_jemallocator::Jemalloc` as the global allocator add this to your project:
37
38```rust
39# main.rs
40#[cfg(not(target_env = "msvc"))]
41use tikv_jemallocator::Jemalloc;
42
43#[cfg(not(target_env = "msvc"))]
44#[global_allocator]
45static GLOBAL: Jemalloc = Jemalloc;
46```
47
48And that's it! Once you've defined this `static` then jemalloc will be used for
49all allocations requested by Rust code in the same program.
50
51## Platform support
52
53The following table describes the supported platforms:
54
55* `build`: does the library compile for the target?
56* `run`: do `tikv-jemallocator` and `tikv-jemalloc-sys` tests pass on the target?
57* `jemalloc`: do `tikv-jemalloc`'s tests pass on the target?
58
59Tier 1 targets are tested on all Rust channels (stable, beta, and nightly). All
60other targets are only tested on Rust nightly.
61
62| Linux targets: | build | run | jemalloc |
63|-------------------------------------|-----------|---------|--------------|
64| `aarch64-unknown-linux-gnu` | ✓ | ✓ | ✗ |
65| `powerpc64le-unknown-linux-gnu` | ✓ | ✓ | ✗ |
66| `x86_64-unknown-linux-gnu` (tier 1) | ✓ | ✓ | ✓ |
67| **MacOSX targets:** | **build** | **run** | **jemalloc** |
68| `x86_64-apple-darwin` (tier 1) | ✓ | ✓ | ✗ |
69
70## Features
71
72The `tikv-jemallocator` crate re-exports the [features of the `tikv-jemalloc-sys`
73dependency](https://github.com/tikv/jemallocator/blob/master/jemalloc-sys/README.md).
74
75## License
76
77This project is licensed under either of
78
79 * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
80 http://www.apache.org/licenses/LICENSE-2.0)
81 * MIT license ([LICENSE-MIT](LICENSE-MIT) or
82 http://opensource.org/licenses/MIT)
83
84at your option.
85
86## Contribution
87
88Unless you explicitly state otherwise, any contribution intentionally submitted
89for inclusion in `tikv-jemallocator` by you, as defined in the Apache-2.0 license,
90shall be dual licensed as above, without any additional terms or conditions.
91
92[Latest Version]: https://img.shields.io/crates/v/tikv-jemallocator.svg
93[crates.io]: https://crates.io/crates/tikv-jemallocator
94[docs]: https://docs.rs/tikv-jemallocator/badge.svg
95[docs.rs]: https://docs.rs/tikv-jemallocator/
96[ci]: https://github.com/tikv/jemallocator/actions/workflows/main.yml/badge.svg
97[github actions]: https://github.com/tikv/jemallocator/actions
98
