tikv_jemalloc_ctl/opt.rs
1//! `jemalloc`'s run-time configuration.
2//!
3//! These settings are controlled by the `MALLOC_CONF` environment variable.
4
5option! {
6 abort[ str: b"opt.abort\0", non_str: 2 ] => bool |
7 ops: r |
8 docs:
9 /// Whether `jemalloc` calls `abort(3)` on most warnings.
10 ///
11 /// This is disabled by default unless `--enable-debug` was specified during
12 /// build configuration.
13 ///
14 /// # Examples
15 ///
16 /// ```
17 /// # #[global_allocator]
18 /// # static ALLOC: tikv_jemallocator::Jemalloc = tikv_jemallocator::Jemalloc;
19 /// #
20 /// # fn main() {
21 /// use tikv_jemalloc_ctl::opt;
22 /// let abort = opt::abort::mib().unwrap();
23 /// println!("abort on warning: {}", abort.read().unwrap());
24 /// # }
25 /// ```
26 mib_docs: /// See [`abort`].
27}
28
29option! {
30 dss[ str: b"opt.dss\0", str: 2 ] => &'static str |
31 ops: r |
32 docs:
33 /// The `dss` (`sbrk(2)`) allocation precedence as related to `mmap(2)`
34 /// allocation.
35 ///
36 /// The following settings are supported if `sbrk(2)` is supported by the
37 /// operating system: "disabled", "primary", and "secondary"; otherwise only
38 /// "disabled" is supported. The default is "secondary" if `sbrk(2)` is
39 /// supported by the operating system; "disabled" otherwise.
40 ///
41 /// # Examples
42 ///
43 /// ```
44 /// # #[global_allocator]
45 /// # static ALLOC: tikv_jemallocator::Jemalloc = tikv_jemallocator::Jemalloc;
46 /// #
47 /// # fn main() {
48 /// use tikv_jemalloc_ctl::opt;
49 /// let dss = opt::dss::read().unwrap();
50 /// println!("dss priority: {}", dss);
51 /// # }
52 /// ```
53 mib_docs: /// See [`dss`].
54}
55
56option! {
57 narenas[ str: b"opt.narenas\0", non_str: 2 ] => libc::c_uint |
58 ops: r |
59 docs:
60 /// Maximum number of arenas to use for automatic multiplexing of threads
61 /// and arenas.
62 ///
63 /// The default is four times the number of CPUs, or one if there is a
64 /// single CPU.
65 ///
66 /// # Examples
67 ///
68 /// ```
69 /// # #[global_allocator]
70 /// # static ALLOC: tikv_jemallocator::Jemalloc = tikv_jemallocator::Jemalloc;
71 /// #
72 /// # fn main() {
73 /// use tikv_jemalloc_ctl::opt;
74 /// let narenas = opt::narenas::read().unwrap();
75 /// println!("number of arenas: {}", narenas);
76 /// # }
77 /// ```
78 mib_docs: /// See [`narenas`].
79}
80
81option! {
82 junk[ str: b"opt.junk\0", str: 2 ] => &'static str |
83 ops: r |
84 docs:
85 /// `jemalloc`'s junk filling mode.
86 ///
87 /// Requires `--enable-fill` to have been specified during build
88 /// configuration.
89 ///
90 /// If set to "alloc", each byte of uninitialized allocated memory will be
91 /// set to `0x5a`. If set to "free", each byte of deallocated memory will be set
92 /// to `0x5a`. If set to "true", both allocated and deallocated memory will be
93 /// initialized, and if set to "false" junk filling will be disabled. This is
94 /// intended for debugging and will impact performance negatively.
95 ///
96 /// The default is "false", unless `--enable-debug` was specified during
97 /// build configuration, in
98 /// which case the default is "true".
99 ///
100 /// # Examples
101 ///
102 /// ```
103 /// # #[global_allocator]
104 /// # static ALLOC: tikv_jemallocator::Jemalloc = tikv_jemallocator::Jemalloc;
105 /// #
106 /// # fn main() {
107 /// use tikv_jemalloc_ctl::opt;
108 /// let junk = opt::junk::read().unwrap();
109 /// println!("junk filling: {}", junk);
110 /// # }
111 /// ```
112 mib_docs: /// See [`junk`].
113}
114
115option! {
116 zero[ str: b"opt.zero\0", non_str: 2 ] => bool |
117 ops: r |
118 docs:
119 /// `jemalloc`'s zeroing behavior.
120 ///
121 /// Requires `--enable-fill` to have been specified during build
122 /// configuration.
123 ///
124 /// If enabled, `jemalloc` will initialize each byte of uninitialized
125 /// allocated memory to 0. This is intended for debugging and will impact
126 /// performance negatively. It is disabled by default.
127 ///
128 /// # Examples
129 ///
130 /// ```
131 /// # #[global_allocator]
132 /// # static ALLOC: tikv_jemallocator::Jemalloc = tikv_jemallocator::Jemalloc;
133 /// #
134 /// # fn main() {
135 /// use tikv_jemalloc_ctl::opt;
136 /// let zero = opt::zero::read().unwrap();
137 /// println!("zeroing: {}", zero);
138 /// # }
139 /// ```
140 mib_docs: /// See [`zero`].
141}
142
143option! {
144 tcache[ str: b"opt.tcache\0", non_str: 2 ] => bool |
145 ops: r |
146 docs:
147 /// Thread-local allocation caching behavior.
148 ///
149 /// Thread-specific caching allows many allocations to be satisfied without
150 /// performing any thread synchronization, at the cost of increased memory
151 /// use. This is enabled by default.
152 ///
153 /// # Examples
154 ///
155 /// ```
156 /// # #[global_allocator]
157 /// # static ALLOC: tikv_jemallocator::Jemalloc = tikv_jemallocator::Jemalloc;
158 /// #
159 /// # fn main() {
160 /// use tikv_jemalloc_ctl::opt;
161 /// let tcache = opt::tcache::read().unwrap();
162 /// println!("thread-local caching: {}", tcache);
163 /// # }
164 /// ```
165 mib_docs: /// See [`tcache`].
166}
167
168option! {
169 tcache_max[ str: b"opt.tcache_max\0", non_str: 2 ] => libc::size_t |
170 ops: r |
171 docs:
172 /// Maximum size class (log base 2) to cache in the thread-specific cache
173 /// (`tcache`).
174 ///
175 /// At a minimum, all small size classes are cached, and at a maximum all
176 /// large size classes are cached. The default maximum is 32 KiB (2^15).
177 ///
178 /// # Examples
179 ///
180 /// ```
181 /// # #[global_allocator]
182 /// # static ALLOC: tikv_jemallocator::Jemalloc = tikv_jemallocator::Jemalloc;
183 /// #
184 /// # fn main() {
185 /// use tikv_jemalloc_ctl::opt;
186 /// let tcache_max = opt::tcache_max::read().unwrap();
187 /// println!("max cached allocation size: {}", tcache_max);
188 /// # }
189 /// ```
190 mib_docs: /// See [`tcache_max`].
191}
192
193option! {
194 background_thread[ str: b"opt.background_thread\0", non_str: 2 ] => bool |
195 ops: r |
196 docs:
197 /// `jemalloc`'s default initialization behavior for background threads.
198 ///
199 /// `jemalloc` automatically spawns background worker threads on
200 /// initialization (first `jemalloc` call) if this option is enabled. By
201 /// default this option is disabled - `malloc_conf=background_thread:true`
202 /// changes its default.
203 ///
204 /// # Examples
205 ///
206 /// ```
207 /// # #[global_allocator]
208 /// # static ALLOC: tikv_jemallocator::Jemalloc = tikv_jemallocator::Jemalloc;
209 /// #
210 /// # fn main() {
211 /// use tikv_jemalloc_ctl::opt;
212 /// let background_thread = opt::background_thread::read().unwrap();
213 /// println!("background threads since initialization: {}", background_thread);
214 /// # }
215 /// ```
216 mib_docs: /// See [`background_thread`].
217}