update documentation on options

Author: daanx

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;
 

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,