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 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:
//!
//! ```no_run
//! 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));
//!     }
//! }
//! ```
// 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: jemallocator::Jemalloc = 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: jemallocator::Jemalloc = jemallocator::Jemalloc;
    /// #
    /// # fn main() {
    /// use 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: jemallocator::Jemalloc = jemallocator::Jemalloc;
    /// #
    /// # fn main() {
    /// # #[cfg(not(target_os = "macos"))] {
    /// #
    /// use 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: jemallocator::Jemalloc = jemallocator::Jemalloc;
    /// #
    /// # fn main() {
    /// # #[cfg(not(target_os = "macos"))] {
    /// #
    /// use 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: jemallocator::Jemalloc = jemallocator::Jemalloc;
    /// #
    /// # fn main() {
    /// #
    /// use 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)
    }
}