Crate jemalloc_ctl

jemalloc control and introspection.

jemalloc offers a powerful introspection and control interface through the mallctl function. It can be used to tune the allocator, take heap dumps, and retrieve statistics. This crate provides a typed API over that interface.

While mallctl takes a string to specify an operation (e.g. stats.allocated or stats.arenas.15.muzzy_decay_ms), the overhead of repeatedly parsing those strings is not ideal. Fortunately, jemalloc offers the ability to translate the string ahead of time into a “Management Information Base” (MIB) to speed up future lookups.

This crate provides a type for each mallctl operation. Calling $op::{read(), write(x), update(x)} on the type calls mallctl with the string-based API. If the operation will be repeatedly performed, a MIB for the operation can be obtained using $op.mib().

Examples

Repeatedly printing allocation statistics:

use std::thread;
use std::time::Duration;
use jemalloc_ctl::{stats, epoch};

#[global_allocator]
static ALLOC: jemallocator::Jemalloc = jemallocator::Jemalloc;

fn main() {
    loop {
        // many statistics are cached and only updated when the epoch is advanced.
        epoch::advance().unwrap();

        let allocated = stats::allocated::read().unwrap();
        let resident = stats::resident::read().unwrap();
        println!("{} bytes allocated/{} bytes resident", allocated, resident);
        thread::sleep(Duration::from_secs(10));
    }
}

Doing the same with the MIB-based API:

use std::thread;
use std::time::Duration;
use jemalloc_ctl::{stats, epoch};

#[global_allocator]
static ALLOC: jemallocator::Jemalloc = jemallocator::Jemalloc;

fn main() {
    let e = epoch::mib().unwrap();
    let allocated = stats::allocated::mib().unwrap();
    let resident = stats::resident::mib().unwrap();
    loop {
        // many statistics are cached and only updated when the epoch is advanced.
        e.advance().unwrap();

        let allocated = allocated.read().unwrap();
        let resident = resident.read().unwrap();
        println!("{} bytes allocated/{} bytes resident", allocated, resident);
        thread::sleep(Duration::from_secs(10));
    }
}

Modules

• arenas
  Arena operations.
• config
  jemalloc’s build-time configuration.
• opt
  jemalloc’s run-time configuration.
• raw
  Raw unsafe access to the malloctl API.
• stats
  Global allocator statistics.
• thread
  Thread specific operations.

Structs

• Error
  Errors of the jemalloc_sys::mallct-family of functions.
• Mib
  Management Information Base of a non-string value.
• MibStr
  Management Information Base of a string value.
• Name
  A Name in the MALLCTL NAMESPACE.
• background_thread
  State of internal background worker threads.
• background_thread_mib
  See background_thread.
• epoch
  jemalloc epoch.
• epoch_mib
  See epoch.
• max_background_threads
  Maximum number of background threads that will be created.
• max_background_threads_mib
  See max_background_threads.
• version
  jemalloc version string.
• version_mib
  See version.

Traits

• Access
  Safe read access to the MALLCTL NAMESPACE.
• AsName
  Converts a null-terminated byte-string into a Name.

Type Definitions

• Result
  Result type