1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224
//! `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:
//!
//! ```no_run
//! use std::thread;
//! use std::time::Duration;
//! use tikv_jemalloc_ctl::{stats, epoch};
//!
//! #[global_allocator]
//! static ALLOC: tikv_jemallocator::Jemalloc = tikv_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:
//!
//! ```no_run
//! use std::thread;
//! use std::time::Duration;
//! use tikv_jemalloc_ctl::{stats, epoch};
//!
//! #[global_allocator]
//! static ALLOC: tikv_jemallocator::Jemalloc = tikv_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));
//! }
//! }
//! ```
// TODO: rename the following lint on next minor bump
#![allow(renamed_and_removed_lints)]
#![deny(missing_docs, broken_intra_doc_links)]
#![cfg_attr(not(feature = "use_std"), no_std)]
#![cfg_attr(feature = "cargo-clippy", allow(clippy::module_name_repetitions))]
#[cfg(test)]
#[global_allocator]
static ALLOC: tikv_jemallocator::Jemalloc = tikv_jemallocator::Jemalloc;
use crate::std::{fmt, mem, num, ops, ptr, result, slice, str};
#[cfg(not(feature = "use_std"))]
use core as std;
#[cfg(feature = "use_std")]
use std;
#[macro_use]
mod macros;
pub mod arenas;
pub mod config;
mod error;
mod keys;
pub mod opt;
pub mod raw;
pub mod stats;
#[cfg(feature = "use_std")]
pub mod stats_print;
pub mod thread;
pub use error::{Error, Result};
pub use keys::{Access, AsName, Mib, MibStr, Name};
option! {
version[ str: b"version\0", str: 1 ] => &'static str |
ops: r |
docs:
/// `jemalloc` version string.
///
/// # Example
///
/// ```
/// # #[global_allocator]
/// # static ALLOC: tikv_jemallocator::Jemalloc = tikv_jemallocator::Jemalloc;
/// #
/// # fn main() {
/// use tikv_jemalloc_ctl::version;
/// println!("jemalloc version {}", version::read().unwrap());
/// let version_mib = version::mib().unwrap();
/// println!("jemalloc version {}", version_mib.read().unwrap());
/// # }
/// ```
mib_docs: /// See [`version`].
}
option! {
background_thread[ str: b"background_thread\0", non_str: 1 ] => bool |
ops: r,w,u |
docs:
/// State of internal background worker threads.
///
/// When enabled, background threads are created on demand (the number of
/// background threads will be no more than the number of CPUs or active
/// arenas). Threads run periodically and handle purging asynchronously.
///
/// ```
/// # #[global_allocator]
/// # static ALLOC: tikv_jemallocator::Jemalloc = tikv_jemallocator::Jemalloc;
/// #
/// # fn main() {
/// # #[cfg(not(target_os = "macos"))] {
/// #
/// use tikv_jemalloc_ctl::background_thread;
/// let bg = background_thread::mib().unwrap();
/// let s = bg.read().unwrap();
/// println!("background_threads enabled: {}", s);
/// let p = background_thread::update(!s).unwrap();
/// println!("background_threads enabled: {} => {}", p, bg.read().unwrap());
/// assert_eq!(p, s);
/// background_thread::write(s).unwrap();
/// println!("background_threads enabled: {}", bg.read().unwrap());
/// assert_eq!(p, s);
/// #
/// # } // #[cfg(..)]
/// # }
/// ```
mib_docs: /// See [`background_thread`].
}
option! {
max_background_threads[ str: b"max_background_threads\0", non_str: 1 ] => libc::size_t |
ops: r, w, u |
docs:
/// Maximum number of background threads that will be created.
///
/// ```
/// # #[global_allocator]
/// # static ALLOC: tikv_jemallocator::Jemalloc = tikv_jemallocator::Jemalloc;
/// #
/// # fn main() {
/// # #[cfg(not(target_os = "macos"))] {
/// #
/// use tikv_jemalloc_ctl::max_background_threads;
/// let m = max_background_threads::mib().unwrap();
/// println!("max_background_threads: {}", m.read().unwrap());
/// m.write(2).unwrap();
/// assert_eq!(m.read().unwrap(), 2);
/// #
/// # } // #[cfg(..)]
/// # }
/// ```
mib_docs: /// See [`max_background_threads`].
}
option! {
epoch[ str: b"epoch\0", non_str: 1 ] => u64 |
ops: r, w, u |
docs:
/// `jemalloc` epoch.
///
/// Many of the statistics tracked by `jemalloc` are cached. The epoch
/// controls when they are refreshed.
///
/// # Example
///
/// Advancing the epoch:
///
/// ```
/// # #[global_allocator]
/// # static ALLOC: tikv_jemallocator::Jemalloc = tikv_jemallocator::Jemalloc;
/// #
/// # fn main() {
/// #
/// use tikv_jemalloc_ctl::epoch;
/// let e = epoch::mib().unwrap();
/// let a = e.advance().unwrap();
/// let b = e.advance().unwrap();
/// assert_eq!(a + 1, b);
///
/// let o = e.update(0).unwrap();
/// assert_eq!(o, e.read().unwrap());
/// # }
mib_docs: /// See [`epoch`].
}
impl epoch {
/// Advances the epoch returning its old value - see [`epoch`].
pub fn advance() -> crate::error::Result<u64> {
Self::update(1)
}
}
impl epoch_mib {
/// Advances the epoch returning its old value - see [`epoch`].
pub fn advance(self) -> crate::error::Result<u64> {
self.0.update(1)
}
}