From 08e0f14c2a34198da5eb7d343ab448e4fc7b20b8 Mon Sep 17 00:00:00 2001
From: daan <daanl@outlook.com>
Date: Mon, 15 Jul 2019 14:32:54 -0700
Subject: [PATCH] document experimental options

---
 include/mimalloc.h | 10 ++++++----
 src/options.c      | 24 ++++++++++++++----------
 2 files changed, 20 insertions(+), 14 deletions(-)

diff --git a/include/mimalloc.h b/include/mimalloc.h
index 2c4632d1..1f80027c 100644
--- a/include/mimalloc.h
+++ b/include/mimalloc.h
@@ -218,17 +218,19 @@ mi_decl_export bool mi_heap_visit_blocks(const mi_heap_t* heap, bool visit_all_b
 // ------------------------------------------------------
 
 typedef enum mi_option_e {
+  // stable options
+  mi_option_show_stats,
+  mi_option_show_errors,
+  mi_option_verbose,
+  // the following options are experimental
   mi_option_page_reset,
   mi_option_cache_reset,
   mi_option_eager_commit,
   mi_option_eager_region_commit,
-  mi_option_large_os_pages,  // implies eager commit
+  mi_option_large_os_pages,      // implies eager commit
   mi_option_reset_decommits,
   mi_option_reset_discards,
   mi_option_secure,
-  mi_option_show_stats,
-  mi_option_show_errors,
-  mi_option_verbose,
   _mi_option_last
 } mi_option_t;
 
diff --git a/src/options.c b/src/options.c
index 9f408874..ac0910a0 100644
--- a/src/options.c
+++ b/src/options.c
@@ -31,22 +31,26 @@ typedef struct mi_option_desc_s {
   const char* name;   // option name without `mimalloc_` prefix
 } mi_option_desc_t;
 
-static mi_option_desc_t options[_mi_option_last] = {
+static mi_option_desc_t options[_mi_option_last] = 
+{
+  // stable options
+  { 0, UNINIT, "show_stats" },
+  { MI_DEBUG, UNINIT, "show_errors" },
+  { 0, UNINIT, "verbose" },
+
+  // the following options are experimental and not all combinations make sense.
   { 0, UNINIT, "page_reset" },
   { 0, UNINIT, "cache_reset" },
   { 1, UNINIT, "eager_commit" },     
-  { 1, UNINIT, "eager_region_commit" },
-  { 0, UNINIT, "large_os_pages" },   // use large OS pages, use only with eager commit to prevent fragmentation of VMA's
-  { 0, UNINIT, "reset_decommits" },
-  { 0, UNINIT, "reset_discards" },
+  { 1, UNINIT, "eager_region_commit" }, // eager_commit should be on when eager_region_commit is on 
+  { 0, UNINIT, "large_os_pages" },      // use large OS pages, use only with eager commit to prevent fragmentation of VMA's
+  { 0, UNINIT, "reset_decommits" },     
+  { 0, UNINIT, "reset_discards" },   
   #if MI_SECURE
-  { MI_SECURE, INITIALIZED, "secure" }, // in secure build the environment setting is ignored
+  { MI_SECURE, INITIALIZED, "secure" } // in a secure build the environment setting is ignored
   #else
-  { 0, UNINIT, "secure" },
+  { 0, UNINIT, "secure" }              
   #endif
-  { 0, UNINIT, "show_stats" },
-  { MI_DEBUG, UNINIT, "show_errors" },
-  { 0, UNINIT, "verbose" }
 };
 
 static void mi_option_init(mi_option_desc_t* desc);