Skip to content

Commit 5bfe2b8

Browse files
authored
Merge pull request #37 from linxGnu/update_extended_opts
NO-ISSUE Expose extended experimental options
2 parents 0759915 + d06bcf2 commit 5bfe2b8

File tree

2 files changed

+97
-5
lines changed

2 files changed

+97
-5
lines changed

libmimalloc-sys/build.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -113,7 +113,7 @@ fn main() {
113113

114114
let mut out_dir = "./build".to_string();
115115
if cfg!(all(windows, target_env = "msvc")) {
116-
out_dir.push_str("/");
116+
out_dir.push('/');
117117
out_dir.push_str(win_folder);
118118
}
119119
let out_name = if cfg!(all(windows, target_env = "msvc")) {

libmimalloc-sys/src/extended.rs

Lines changed: 96 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -316,10 +316,6 @@ pub type mi_deferred_free_fun =
316316
pub type mi_error_fun = Option<unsafe extern "C" fn(code: c_int, arg: *mut c_void)>;
317317

318318
/// Runtime options. All options are false by default.
319-
///
320-
/// Note: Currently experimental options (values > `mi_option_verbose` are not
321-
/// given named constants), as they may change and make exposing a stable API
322-
/// difficult.
323319
pub type mi_option_t = c_int;
324320

325321
// Note: mimalloc doc website seems to have the order of show_stats and
@@ -335,6 +331,82 @@ pub const mi_option_show_stats: mi_option_t = 1;
335331
/// Option allowing printing verbose messages to stderr.
336332
pub const mi_option_verbose: mi_option_t = 2;
337333

334+
/// Option (experimental) specifying eagerly commit segments (4MiB) (enabled by default).
335+
pub const mi_option_eager_commit: mi_option_t = 3;
336+
337+
/// Option (experimental) specifying eagerly commit large (256MiB) memory regions (enabled by default, except on Windows).
338+
pub const mi_option_eager_region_commit: mi_option_t = 4;
339+
340+
/// Experimental
341+
pub const mi_option_reset_decommits: mi_option_t = 5;
342+
343+
/// Option (experimental) to use large OS pages (2MiB in size) if possible.
344+
///
345+
/// Use large OS pages (2MiB) when available; for some workloads this can
346+
/// significantly improve performance. Use mi_option_verbose to check if
347+
/// the large OS pages are enabled -- usually one needs to explicitly allow
348+
/// large OS pages (as on Windows and Linux). However, sometimes the OS is
349+
/// very slow to reserve contiguous physical memory for large OS pages so
350+
/// use with care on systems that can have fragmented memory (for that
351+
/// reason, we generally recommend to use mi_option_reserve_huge_os_pages
352+
/// instead whenever possible).
353+
pub const mi_option_large_os_pages: mi_option_t = 6;
354+
355+
/// Option (experimental) specifying number of huge OS pages (1GiB in size) to reserve at the start of the program.
356+
///
357+
/// This reserves the huge pages at startup and sometimes this can give a large (latency) performance
358+
/// improvement on big workloads. Usually it is better to not use MIMALLOC_LARGE_OS_PAGES in
359+
/// combination with this setting. Just like large OS pages, use with care as reserving contiguous
360+
/// physical memory can take a long time when memory is fragmented (but reserving the huge pages is
361+
/// done at startup only once). Note that we usually need to explicitly enable huge OS pages (as on
362+
/// Windows and Linux)). With huge OS pages, it may be beneficial to set the setting
363+
/// mi_option_eager_commit_delay=N (N is 1 by default) to delay the initial N segments (of 4MiB) of
364+
/// a thread to not allocate in the huge OS pages; this prevents threads that are short lived and
365+
/// allocate just a little to take up space in the huge OS page area (which cannot be reset).
366+
pub const mi_option_reserve_huge_os_pages: mi_option_t = 7;
367+
368+
/// Option (experimental) specifying number of segments per thread to keep cached.
369+
pub const mi_option_segment_cache: mi_option_t = 8;
370+
371+
/// Option (experimental) to reset page memory after mi_option_reset_delay milliseconds when it becomes free.
372+
///
373+
/// By default, mimalloc will reset (or purge) OS pages that are not in use, to signal to the OS
374+
/// that the underlying physical memory can be reused. This can reduce memory fragmentation in
375+
/// long running (server) programs. By setting it to 0 this will no longer be done which can improve
376+
/// performance for batch-like programs. As an alternative, the mi_option_reset_delay= can be set
377+
/// higher (100ms by default) to make the page reset occur less frequently instead of turning it
378+
/// off completely.
379+
///
380+
/// Default: 1 (true)
381+
pub const mi_option_page_reset: mi_option_t = 9;
382+
383+
/// Experimental
384+
pub const mi_option_abandoned_page_reset: mi_option_t = 10;
385+
386+
/// Experimental
387+
pub const mi_option_segment_reset: mi_option_t = 11;
388+
389+
/// Experimental
390+
pub const mi_option_eager_commit_delay: mi_option_t = 12;
391+
392+
/// Option (experimental) specifying delay in milli-seconds before resetting a page (100ms by default).
393+
pub const mi_option_reset_delay: mi_option_t = 13;
394+
395+
/// Option (experimental) to pretend there are at most N NUMA nodes.
396+
///
397+
/// If not set, the actual NUMA nodes are detected at runtime. Setting N to 1 may avoid
398+
/// problems in some virtual environments. Also, setting it to a lower number than the
399+
/// actual NUMA nodes is fine and will only cause threads to potentially allocate more
400+
/// memory across actual NUMA nodes (but this can happen in any case as NUMA local
401+
/// allocation is always a best effort but not guaranteed).
402+
pub const mi_option_use_numa_nodes: mi_option_t = 14;
403+
404+
/// Option (experimental) specifying OS tag to assign to mimalloc'd memory.
405+
pub const mi_option_os_tag: mi_option_t = 15;
406+
407+
/// Experimental
408+
pub const mi_option_max_errors: mi_option_t = 16;
409+
338410
extern "C" {
339411
// Note: mi_option_{enable,disable} aren't exposed because they're redundant
340412
// and because of https://github.com/microsoft/mimalloc/issues/266.
@@ -682,3 +754,23 @@ extern "C" {
682754
arg: *mut c_void,
683755
) -> bool;
684756
}
757+
758+
#[cfg(test)]
759+
mod tests {
760+
use super::*;
761+
762+
#[test]
763+
fn runtime_option_page_reset() {
764+
unsafe {
765+
// page reset
766+
assert_eq!(mi_option_get(mi_option_page_reset), 1);
767+
mi_option_set(mi_option_page_reset, 2);
768+
assert_eq!(mi_option_get(mi_option_page_reset), 2);
769+
770+
// page reset delay
771+
assert_eq!(mi_option_get(mi_option_reset_delay), 100);
772+
mi_option_set(mi_option_reset_delay, 10_000);
773+
assert_eq!(mi_option_get(mi_option_reset_delay), 10_000);
774+
}
775+
}
776+
}

0 commit comments

Comments
 (0)