From f515b80093cfd5893070169a439d77616a48f8d8 Mon Sep 17 00:00:00 2001 From: Daan Date: Wed, 2 Feb 2022 19:19:03 -0800 Subject: [PATCH] update documentation on options --- doc/mimalloc-doc.h | 22 +++++++++++++++++----- include/mimalloc.h | 32 ++++++++++++++++---------------- 2 files changed, 33 insertions(+), 21 deletions(-) diff --git a/doc/mimalloc-doc.h b/doc/mimalloc-doc.h index 4cf8c2c3..ea2a1ad5 100644 --- a/doc/mimalloc-doc.h +++ b/doc/mimalloc-doc.h @@ -802,20 +802,32 @@ typedef enum mi_option_e { mi_option_show_errors, ///< Print error messages to `stderr`. mi_option_show_stats, ///< Print statistics to `stderr` when the program is done. mi_option_verbose, ///< Print verbose messages to `stderr`. + // the following options are experimental mi_option_eager_commit, ///< Eagerly commit segments (4MiB) (enabled by default). - mi_option_eager_region_commit, ///< Eagerly commit large (256MiB) memory regions (enabled by default, except on Windows) mi_option_large_os_pages, ///< Use large OS pages (2MiB in size) if possible mi_option_reserve_huge_os_pages, ///< The number of huge OS pages (1GiB in size) to reserve at the start of the program. mi_option_reserve_huge_os_pages_at, ///< Reserve huge OS pages at node N. - mi_option_segment_cache, ///< The number of segments per thread to keep cached. + mi_option_reserve_os_memory, ///< Reserve specified amount of OS memory at startup, e.g. "1g" or "512m". + mi_option_segment_cache, ///< The number of segments per thread to keep cached (0). mi_option_page_reset, ///< Reset page memory after \a mi_option_reset_delay milliseconds when it becomes free. + mi_option_abandoned_page_reset, //< Reset free page memory when a thread terminates. + mi_option_use_numa_nodes, ///< Pretend there are at most N NUMA nodes; Use 0 to use the actual detected NUMA nodes at runtime. + mi_option_eager_commit_delay, ///< the first N segments per thread are not eagerly committed (=1). + mi_option_os_tag, ///< OS tag to assign to mimalloc'd memory + mi_option_limit_os_alloc, ///< If set to 1, do not use OS memory for allocation (but only pre-reserved arenas) + + // v1.x specific options + mi_option_eager_region_commit, ///< Eagerly commit large (256MiB) memory regions (enabled by default, except on Windows) mi_option_segment_reset, ///< Experimental mi_option_reset_delay, ///< Delay in milli-seconds before resetting a page (100ms by default) - mi_option_use_numa_nodes, ///< Pretend there are at most N NUMA nodes mi_option_reset_decommits, ///< Experimental - mi_option_eager_commit_delay, ///< Experimental - mi_option_os_tag, ///< OS tag to assign to mimalloc'd memory + + // v2.x specific options + mi_option_allow_decommit, ///< Enable decommitting memory (=on) + mi_option_decommit_delay, ///< Decommit page memory after N milli-seconds delay (25ms). + mi_option_segment_decommit_delay, ///< Decommit large segment memory after N milli-seconds delay (500ms). + _mi_option_last } mi_option_t; diff --git a/include/mimalloc.h b/include/mimalloc.h index 6f950751..0b84f6c3 100644 --- a/include/mimalloc.h +++ b/include/mimalloc.h @@ -296,30 +296,30 @@ mi_decl_export int mi_reserve_huge_os_pages(size_t pages, double max_secs, size // ------------------------------------------------------ -// Options, all `false` by default +// Options // ------------------------------------------------------ typedef enum mi_option_e { // stable options - mi_option_show_errors, - mi_option_show_stats, - mi_option_verbose, - // the following options are experimental - mi_option_eager_commit, - mi_option_eager_region_commit, + mi_option_show_errors, // print error messages + mi_option_show_stats, // print statistics on termination + mi_option_verbose, // print verbose messages + // the following options are experimental (see src/options.h) + mi_option_eager_commit, + mi_option_eager_region_commit, mi_option_reset_decommits, - mi_option_large_os_pages, // implies eager commit - mi_option_reserve_huge_os_pages, - mi_option_reserve_huge_os_pages_at, - mi_option_reserve_os_memory, - mi_option_segment_cache, - mi_option_page_reset, - mi_option_abandoned_page_reset, + mi_option_large_os_pages, // use large (2MiB) OS pages, implies eager commit + mi_option_reserve_huge_os_pages, // reserve N huge OS pages (1GiB) at startup + mi_option_reserve_huge_os_pages_at, // reserve huge OS pages at a specific NUMA node + mi_option_reserve_os_memory, // reserve specified amount of OS memory at startup + mi_option_segment_cache, + mi_option_page_reset, + mi_option_abandoned_page_reset, mi_option_segment_reset, mi_option_eager_commit_delay, mi_option_reset_delay, - mi_option_use_numa_nodes, - mi_option_limit_os_alloc, + mi_option_use_numa_nodes, // 0 = use available numa nodes, otherwise use at most N nodes. + mi_option_limit_os_alloc, // 1 = do not use OS memory for allocation (but only reserved arenas) mi_option_os_tag, mi_option_max_errors, mi_option_max_warnings,