This crate requires a nightly (unstable, experimental) compiler version. To switch to it, you must have Rust installed via Rustup, and run:

rustup default nightly

Run rustup default stable to switch back.

Adding `unkai` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add unkai

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

unkai = "0.2.0"

The unkai library will be automatically available globally. Read the unkai library documentation.

Back to the crate overview.

Readme

unkai

Unkai is a tool set for Rust's memory allocation APIs mainly focus on tracking and conditional analyzing / limiting memory usage.

Basic Usage

It's now compatible with two major forms of allocator API in the standard library:

GlobalAlloc : the global memory allocator for all default memory allocation.
Allocator : the unstable allocator API (tracking issue) that allows changing Allocator for a specific struct like Box or Vec.

Use with `GlobalAlloc`

The entrypoint is UnkaiGlobalAlloc. Only need to wrap your original global allocator with UnkaiGlobalAlloc like this:

use tikv_jemallocator::Jemalloc;
use unkai::UnkaiGlobalAlloc;

#[global_allocator]
static UNKAI: UnkaiGlobalAlloc<Jemalloc> = UnkaiGlobalAlloc::new(Jemalloc {}, 99, 5, 10, 0);

Notice that Allocator only available when the unstable feature allocator_api is enabled via #![feature(allocator_api)]. And enabling unstable feature requires the nigntly channel Rust toolchain.

The entrypoint is Unkai. Example usage:

let mut vec_container: Vec<usize, UnkaiGlobal> = Vec::with_capacity_in(10000, Unkai::default());
assert_eq!(vec_container.allocator().report_usage(), 80000);

There is also an example file examples/allocator.rs that shows more usages.

Tracking allocation

TBD

Supported Feature

GlobalAlloc
- Capture and record backtrace with memory consumption

Roadmap

GlobalAlloc
- Record pointer's lifetime
Allocator
- Tree-structured
- Low-overhead in-use statistics
General
- Prometheus integration
- Build-in report generation

Example

There are some example files under examples/. They are:

allocator.rs: shows the usage of Allocator wrapper to track memory consumption at runtime.
collections.rs: shows the usage of GlobalAlloc and stack tracking

To run example, use command like the following:

cargo run --example collections --release

Adding unkai library as a dependency

Adding `unkai` library as a dependency