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
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
//! [mimalloc](https://github.com/microsoft/mimalloc) v3 as a Rust global
//! allocator.
//!
//! To use mimalloc for every Rust allocation, declare it as the global
//! allocator:
//!
//! ```rust
//! use cyo_mimalloc::MiMalloc;
//!
//! #[global_allocator]
//! static GLOBAL: MiMalloc = MiMalloc;
//! ```
//!
//! The crate is `no_std` and does not use `alloc`. Functions that produce text,
//! such as [`MiMalloc::stats_print`], write it to any [`core::fmt::Write`]. A
//! `String` works, and so do a fixed buffer and a logger that allocates
//! nothing.
//!
//! The global allocator only covers Rust allocations. A C library linked into
//! the same program, for example through a `-sys` crate, still calls the
//! system `malloc`.
//!
//! # Build configuration
//!
//! This crate has no Cargo features. Cargo merges features across the whole
//! dependency tree, so any library could switch on a mode that changes the
//! allocator for the entire program. Instead, you configure mimalloc through
//! environment variables of the build that produces the final binary or shared
//! library. Put them in that project's `.cargo/config.toml`, or in the
//! environment of its Nix derivation or CI job. Cargo does not read the
//! `.cargo/config.toml` of a dependency. Changing any of the variables rebuilds
//! mimalloc.
//!
//! | Variable | Values | Effect |
//! |---|---|---|
//! | `MI_SECURE` | 0 to 4 (default 0) | Secure mode. Higher levels add more protections, such as guard pages, encoded free lists, randomized allocation and double-free detection. Each protection costs some speed. |
//! | `MI_DEBUG` | 0 to 3 (default 0) | Internal assertions (1), plus consistency checks (2), plus expensive checks (3). |
//! | `MI_NO_THP` | 0 or 1 (default 0) | 1 compiles out mimalloc's requests for transparent huge pages. To decide at runtime instead, use the `allow_thp` option. |
//! | `CYO_MIMALLOC_TLS_MODEL` | `initial-exec` (default), `local-dynamic`, `global-dynamic`, `local-exec` | How mimalloc finds its thread-local state. `initial-exec` is the fastest. A shared library that is loaded with `dlopen`, such as a Python extension, needs `local-dynamic`. A build for MSVC checks the value but does not use it. |
//! | `MI_DEFAULT_<NAME>` | see [Build-time defaults](#build-time-defaults) | The default value of a runtime option. |
//!
//! An invalid value stops the build with an error.
//!
//! On MSVC, the build compiles mimalloc with the C runtime that the rest of the
//! build uses. That is `/MT` under `-C target-feature=+crt-static`, and `/MD`
//! otherwise. A statically linked program therefore needs neither
//! `vcruntime140.dll` nor `ucrtbase.dll`. No build variable of this crate
//! selects the runtime, because mixing the two runtimes in one binary is a link
//! error.
//!
//! ```toml
//! # .cargo/config.toml of the application
//! [env]
//! MI_SECURE = "4"
//! CYO_MIMALLOC_TLS_MODEL = "local-dynamic"
//! ```
//!
//! A library that depends on this crate should leave this configuration to the
//! application. It should also not declare a `#[global_allocator]` or call
//! [`MiMalloc::option_set`], because both affect the whole program. For memory
//! of its own, a library can use a [`heap::Heap`], optionally in an exclusive
//! arena from [`heap::reserve_os_memory`].
//!
//! # Options
//!
//! mimalloc has runtime options for things like how quickly unused memory is
//! returned to the OS and whether huge pages are used. [`mi_option_t`] lists
//! them all, with their defaults and when mimalloc reads each one. An option
//! gets its value from, in increasing order of precedence:
//!
//! 1. mimalloc's built-in default;
//! 2. a default chosen when your program is built;
//! 3. an environment variable when your program runs;
//! 4. a call from your code.
//!
//! An application can therefore ship its own defaults, and whoever runs it can
//! still change them.
//!
//! ## Build-time defaults
//!
//! Like the rest of the [build configuration](#build-configuration), every
//! `MI_DEFAULT_<NAME>` variable in the build environment becomes the default
//! for the option `<name>`:
//!
//! ```toml
//! [env]
//! MI_DEFAULT_ALLOW_THP = "0"
//! MI_DEFAULT_ARENA_EAGER_COMMIT = "1"
//! MI_DEFAULT_RESERVE_OS_MEMORY = "1048576" # KiB, so 1 GiB
//! ```
//!
//! Only the options whose [`mi_option_t`] entry names a `MI_DEFAULT_*`
//! variable accept one. The build also accepts
//! `MI_DEFAULT_PHYSICAL_MEMORY_IN_KIB`, which sets the amount of physical memory
//! that mimalloc assumes until it has detected the real amount. The build passes
//! each value to the C compiler unchanged, and sizes are in KiB. The build
//! ignores any other `MI_DEFAULT_*` variable, with a warning.
//!
//! ## Environment variables
//!
//! When the program starts, mimalloc reads `MIMALLOC_<NAME>` for each option,
//! for example `MIMALLOC_PURGE_DELAY=0` or `MIMALLOC_ALLOW_THP=0`. The value
//! overrides the build-time default. Sizes accept a unit here:
//! `MIMALLOC_ARENA_RESERVE=4GiB`. Set `MIMALLOC_VERBOSE=1` to print every
//! option's value at startup.
//!
//! ## From code
//!
//! [`MiMalloc::option_set`], [`option_enable`](MiMalloc::option_enable) and
//! [`option_disable`](MiMalloc::option_disable) override every other source,
//! from the moment you call them:
//!
//! ```rust
//! use cyo_mimalloc::{MiMalloc, mi_option_t};
//!
//! MiMalloc::option_set(mi_option_t::mi_option_purge_delay, 100);
//! MiMalloc::option_enable(mi_option_t::mi_option_purge_decommits);
//! ```
//!
//! mimalloc starts before any Rust code runs, including `main`. The options that
//! it only reads at startup are fixed by then, and setting them from code does
//! nothing. [`mi_option_t`] marks them "read at startup". Set them with a
//! build-time default or an environment variable, or call the function that
//! does the same at run time, where there is one:
//!
//! | Option | In code |
//! |---|---|
//! | `reserve_os_memory` | [`heap::reserve_os_memory`] |
//! | `reserve_huge_os_pages`, `reserve_huge_os_pages_at` | [`heap::reserve_huge_os_pages_interleave`], [`heap::reserve_huge_os_pages_at`] |
//! | `allow_thp` = 0 | `prctl(PR_SET_THP_DISABLE, 1, 0, 0, 0)`, plus setting the option to 0 |
//! | `use_numa_nodes`, `max_vabits`, `pagemap_commit`, `max_errors`, `max_warnings` | none |
//!
//! An option that mimalloc reads "per thread" applies to the threads that
//! start after you change it.
extern crate std;
pub use ;
pub use mi_option_t;
use ;
use c_void;
/// The mimalloc global allocator.
///
/// Every allocation goes through an aligned mimalloc function, such as
/// `mi_malloc_aligned`, so the block meets the alignment of its [`Layout`].
;
// ── GlobalAlloc ─────────────────────────────────────────────────────────────
// SAFETY: each method returns a block from mimalloc that meets the size and
// alignment of `layout`, or null. mimalloc frees and resizes only blocks that
// it allocated, and `GlobalAlloc` passes only those.
unsafe
// ── Tests ───────────────────────────────────────────────────────────────────