Clarify GROWABLE_ARRAYBUFFERS options in warning

site/source/docs/tools_reference/settings_reference.rst

@@ -3415,11 +3415,19 @@ GROWABLE_ARRAYBUFFERS
 
 Enable support for growable views of Wasm memory. This is a recent Web
 platform feature that can make growing the Wasm memory more efficient,
-especially in multi-threaded builds.
+especially in multi-threaded builds. For background, see
+https://github.com/WebAssembly/design/issues/1271
+
 Setting this to 1 will auto-detect the presence of this API and use
 it when available.
 Setting this to 2 will unconditionally require it. This is the only way
 to completely remove the overhead of growable memory + pthreads.
+
+Note that while browser support for this feature is widespread
+(https://caniuse.com/?search=sharedarraybuffer.resize), it was not usable on
+Firefox until Firefox 154,
+https://bugzilla.mozilla.org/show_bug.cgi?id=2021136
+
 This settings does nothing unless ALLOW_MEMORY_GROWTH is set.
 
 Default value: 0

src/settings.js

@@ -2262,11 +2262,19 @@ var JS_BASE64_API = false;
 
 // Enable support for growable views of Wasm memory. This is a recent Web
 // platform feature that can make growing the Wasm memory more efficient,
-// especially in multi-threaded builds.
+// especially in multi-threaded builds. For background, see
+// https://github.com/WebAssembly/design/issues/1271
+//
 // Setting this to 1 will auto-detect the presence of this API and use
 // it when available.
 // Setting this to 2 will unconditionally require it. This is the only way
 // to completely remove the overhead of growable memory + pthreads.
+//
+// Note that while browser support for this feature is widespread
+// (https://caniuse.com/?search=sharedarraybuffer.resize), it was not usable on
+// Firefox until Firefox 154,
+// https://bugzilla.mozilla.org/show_bug.cgi?id=2021136
+//
 // This settings does nothing unless ALLOW_MEMORY_GROWTH is set.
 // [link]
 var GROWABLE_ARRAYBUFFERS = 0;

test/test_other.py

@@ -12139,7 +12139,7 @@ def test_warning_flags(self):
 
     # check that `-Wno-pthreads-mem` disables pthread + ALLOW_GROWTH_MEMORY warning
     stderr = self.run_process(cmd + ['-Wno-pthreads-mem-growth', '-pthread', '-sALLOW_MEMORY_GROWTH'], stderr=PIPE).stderr
-    self.assertNotContained('pthreads + ALLOW_MEMORY_GROWTH may run non-wasm code slowly, see https://github.com/WebAssembly/design/issues/1271', stderr)
+    self.assertNotContained('pthreads + ALLOW_MEMORY_GROWTH may run non-wasm code slowly, consider -sGROWABLE_ARRAYBUFFERS=2', stderr)
 
   def test_emranlib(self):
     create_file('foo.c', 'int foo = 1;')

tools/link.py

@@ -461,7 +461,7 @@ def setup_pthreads():
   if settings.MAIN_MODULE:
     diagnostics.warning('experimental', 'dynamic linking + pthreads is experimental')
   if settings.ALLOW_MEMORY_GROWTH and settings.GROWABLE_ARRAYBUFFERS != 2:
-    diagnostics.warning('pthreads-mem-growth', '-pthread + ALLOW_MEMORY_GROWTH may run non-wasm code slowly, see https://github.com/WebAssembly/design/issues/1271')
+    diagnostics.warning('pthreads-mem-growth', '-pthread + ALLOW_MEMORY_GROWTH may run non-wasm code slowly, consider -sGROWABLE_ARRAYBUFFERS=2')
 
   default_setting('DEFAULT_PTHREAD_STACK_SIZE', settings.STACK_SIZE)