From cdf15b458a1c348722fa43cb1813ac3a93fdc634 Mon Sep 17 00:00:00 2001
From: Qi Wang <interwq@gwu.edu>
Date: Mon, 4 Jun 2018 11:04:29 -0700
Subject: [PATCH] Rename huge_threshold to experimental, and tweak
 documentation.

---
 doc/jemalloc.xml.in | 13 ++++++++-----
 src/ctl.c           |  2 +-
 src/jemalloc.c      |  4 +++-
 src/stats.c         |  2 +-
 test/unit/huge.c    |  2 +-
 test/unit/mallctl.c |  2 +-
 6 files changed, 15 insertions(+), 10 deletions(-)

diff --git a/doc/jemalloc.xml.in b/doc/jemalloc.xml.in
index 1e12fd3a..0dcfb98d 100644
--- a/doc/jemalloc.xml.in
+++ b/doc/jemalloc.xml.in
@@ -1055,7 +1055,9 @@ mallctl("arena." STRINGIFY(MALLCTL_ARENAS_ALL) ".decay",
         linkend="arena.i.dirty_decay_ms"><mallctl>arena.&lt;i&gt;.dirty_decay_ms</mallctl></link>
         for related dynamic control options.  See <link
         linkend="opt.muzzy_decay_ms"><mallctl>opt.muzzy_decay_ms</mallctl></link>
-        for a description of muzzy pages.</para></listitem>
+        for a description of muzzy pages.  Note that when the huge_threshold
+        feature is enabled, the special auto arenas may use its own decay
+        settings.</para></listitem>
       </varlistentry>
 
       <varlistentry id="opt.muzzy_decay_ms">
@@ -1763,10 +1765,11 @@ malloc_conf = "xmalloc:true";]]></programlisting>
         to control allocation for arenas explicitly created via <link
         linkend="arenas.create"><mallctl>arenas.create</mallctl></link> such
         that all extents originate from an application-supplied extent allocator
-        (by specifying the custom extent hook functions during arena creation),
-        but the automatically created arenas will have already created extents
-        prior to the application having an opportunity to take over extent
-        allocation.</para>
+        (by specifying the custom extent hook functions during arena creation).
+        However, the API guarantees for the automatically created arenas may be
+        relaxed -- hooks set there may be called in a "best effort" fashion; in
+        addition there may be extents created prior to the application having an
+        opportunity to take over extent allocation.</para>
 
         <programlisting language="C"><![CDATA[
 typedef extent_hooks_s extent_hooks_t;
diff --git a/src/ctl.c b/src/ctl.c
index 6d0bb92f..5c94cdbc 100644
--- a/src/ctl.c
+++ b/src/ctl.c
@@ -289,7 +289,7 @@ static const ctl_named_node_t opt_node[] = {
 	{NAME("dss"),		CTL(opt_dss)},
 	{NAME("narenas"),	CTL(opt_narenas)},
 	{NAME("percpu_arena"),	CTL(opt_percpu_arena)},
-	{NAME("huge_threshold"),	CTL(opt_huge_threshold)},
+	{NAME("experimental_huge_threshold"),	CTL(opt_huge_threshold)},
 	{NAME("background_thread"),	CTL(opt_background_thread)},
 	{NAME("max_background_threads"),	CTL(opt_max_background_threads)},
 	{NAME("dirty_decay_ms"), CTL(opt_dirty_decay_ms)},
diff --git a/src/jemalloc.c b/src/jemalloc.c
index aded1398..28d1344c 100644
--- a/src/jemalloc.c
+++ b/src/jemalloc.c
@@ -1147,7 +1147,9 @@ malloc_conf_init(void) {
 			CONF_HANDLE_SSIZE_T(opt_lg_tcache_max, "lg_tcache_max",
 			    -1, (sizeof(size_t) << 3) - 1)
 
-			CONF_HANDLE_SIZE_T(opt_huge_threshold, "huge_threshold",
+			/* Experimental feature.  Will be documented later.*/
+			CONF_HANDLE_SIZE_T(opt_huge_threshold,
+			    "experimental_huge_threshold",
 			    LARGE_MINCLASS, LARGE_MAXCLASS, yes, yes, false)
 			CONF_HANDLE_SIZE_T(opt_lg_extent_max_active_fit,
 			    "lg_extent_max_active_fit", 0,
diff --git a/src/stats.c b/src/stats.c
index 9cfc8503..93a04b73 100644
--- a/src/stats.c
+++ b/src/stats.c
@@ -910,7 +910,7 @@ stats_general_print(emitter_t *emitter) {
 	OPT_WRITE_CHAR_P("dss")
 	OPT_WRITE_UNSIGNED("narenas")
 	OPT_WRITE_CHAR_P("percpu_arena")
-	OPT_WRITE_UNSIGNED("huge_threshold")
+	OPT_WRITE_SIZE_T("experimental_huge_threshold")
 	OPT_WRITE_CHAR_P("metadata_thp")
 	OPT_WRITE_BOOL_MUTABLE("background_thread", "background_thread")
 	OPT_WRITE_SSIZE_T_MUTABLE("dirty_decay_ms", "arenas.dirty_decay_ms")
diff --git a/test/unit/huge.c b/test/unit/huge.c
index 7e54d076..f371198f 100644
--- a/test/unit/huge.c
+++ b/test/unit/huge.c
@@ -1,7 +1,7 @@
 #include "test/jemalloc_test.h"
 
 /* Threshold: 2 << 20 = 2097152. */
-const char *malloc_conf = "huge_threshold:2097152";
+const char *malloc_conf = "experimental_huge_threshold:2097152";
 
 #define HUGE_SZ (2 << 20)
 #define SMALL_SZ (8)
diff --git a/test/unit/mallctl.c b/test/unit/mallctl.c
index b4e01af4..d64b4019 100644
--- a/test/unit/mallctl.c
+++ b/test/unit/mallctl.c
@@ -164,7 +164,7 @@ TEST_BEGIN(test_mallctl_opt) {
 	TEST_MALLCTL_OPT(const char *, dss, always);
 	TEST_MALLCTL_OPT(unsigned, narenas, always);
 	TEST_MALLCTL_OPT(const char *, percpu_arena, always);
-	TEST_MALLCTL_OPT(size_t, huge_threshold, always);
+	TEST_MALLCTL_OPT(size_t, experimental_huge_threshold, always);
 	TEST_MALLCTL_OPT(bool, background_thread, always);
 	TEST_MALLCTL_OPT(ssize_t, dirty_decay_ms, always);
 	TEST_MALLCTL_OPT(ssize_t, muzzy_decay_ms, always);