README.md

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);

Use with Allocator

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