Add ASYNCIFY_PROPAGATE_ADD setting, on by default (#21672)

This setting affects whether the ASYNCIFY_ADD list propagates, that is,
whether it automatically leads to more things added based on the
inference. It is on by default, which is safer, but may increase code size
in some cases - to undo that, set it to 0.

Fixes #13150

Author: curiousdannii

ChangeLog.md

@@ -44,6 +44,12 @@ See docs/process.md for more on how version tagging works.
 - TypeScript definitions for Wasm exports, runtime exports, and embind bindings
   can now be generated with `--emit-tsd`. The option `--embind-emit-tsd` has been
   deprecated, use `--emit-tsd` instead.
+- Added the `ASYNCIFY_PROPAGATE_ADD` setting, to control whether the `ASYNCIFY_ADD`
+  list propagates or not. By default this is enabled; as a result you may see larger
+  ASYNCIFY builds as more of the function tree may be instrumented than you were
+  previously manually specifying in `ASYNCIFY_ADD`. To stop propagation you can
+  specify functions in the `ASYNCIFY_REMOVE` list, or to return to the previous
+  behaviour, disable this setting (set `-sNO_ASYNCIFY_PROPAGATE_ADD`.) (#21672)
 - ports changes:
   - Fixed transitive link dependencies (#21602)
   - Enable use of options in ports dependencies (#21629)

site/source/docs/porting/asyncify.rst

@@ -355,12 +355,16 @@ If you know that some indirect calls matter and others do not, then you
 can provide a manual list of functions to Asyncify:
 
 * ``ASYNCIFY_REMOVE`` is a list of functions that do not unwind the stack.
-  Asyncify will do its normal whole-program analysis, then remove these
-  functions from the list of instrumented functions.
-* ``ASYNCIFY_ADD`` is a list of functions that do unwind the stack, and
-  are added after doing the normal whole-program analysis. This is mostly useful
+  As Asyncify processes the call tree, functions in this list will be removed,
+  and neither they nor their callers will be instrumented (unless their callers
+  need to be instrumented for other reasons.)
+* ``ASYNCIFY_ADD`` is a list of functions that do unwind the stack, and will be
+  processed like the imports. This is mostly useful
   if you use ``ASYNCIFY_IGNORE_INDIRECT`` but want to also mark some additional
-  functions that need to unwind.
+  functions that need to unwind. If the ``ASYNCIFY_PROPAGATE_ADD`` setting is
+  disabled however, then this list will only be added after the whole-program
+  analysis. If ``ASYNCIFY_PROPAGATE_ADD`` is disabled then you must also add
+  their callers, their callers' callers, and so on.
 * ``ASYNCIFY_ONLY`` is a list of the **only** functions that can unwind
   the stack. Asyncify will instrument exactly those and no others.
 

site/source/docs/tools_reference/settings_reference.rst

@@ -1131,6 +1131,15 @@ instrumented.
 See notes on ASYNCIFY_REMOVE about the names, including wildcard matching and
 character substitutions.
 
+.. _asyncify_propagate_add:
+
+ASYNCIFY_PROPAGATE_ADD
+======================
+
+If enabled, instrumentation status will be propagated from the add-list, ie.
+their callers, and their callers' callers, and so on. If disabled then all
+callers must be manually added to the add-list (like the only-list).
+
 .. _asyncify_only:
 
 ASYNCIFY_ONLY

src/settings.js

@@ -895,6 +895,12 @@ var ASYNCIFY_REMOVE = [];
 // [link]
 var ASYNCIFY_ADD = [];
 
+// If enabled, instrumentation status will be propagated from the add-list, ie.
+// their callers, and their callers' callers, and so on. If disabled then all
+// callers must be manually added to the add-list (like the only-list).
+// [link]
+var ASYNCIFY_PROPAGATE_ADD = true;
+
 // If the Asyncify only-list is provided, then *only* the functions in the list
 // will be instrumented. Like the remove-list, getting this wrong will break
 // your application.

test/test_core.py

@@ -8221,7 +8221,10 @@ def test_asyncify_lists(self, args, should_pass, response=None):
   @parameterized({
     'normal': ([], True),
     'ignoreindirect': (['-sASYNCIFY_IGNORE_INDIRECT'], False),
-    'add': (['-sASYNCIFY_IGNORE_INDIRECT', '-sASYNCIFY_ADD=["__original_main","main","virt()"]'], True),
+    'add': (['-sASYNCIFY_IGNORE_INDIRECT', '-sASYNCIFY_ADD=["virt()"]'], True),
+    # If ASYNCIFY_PROPAGATE_ADD is disabled then we must specify the callers of
+    # virt() manually, rather than have them inferred automatically.
+    'add_no_prop': (['-sASYNCIFY_IGNORE_INDIRECT', '-sASYNCIFY_ADD=["__original_main","main","virt()"]', '-sASYNCIFY_PROPAGATE_ADD=0'], True),
   })
   def test_asyncify_indirect_lists(self, args, should_pass):
     self.set_setting('ASYNCIFY')

tools/link.py

@@ -370,6 +370,8 @@ def get_binaryen_passes():
       passes += ['--pass-arg=asyncify-verbose']
     if settings.ASYNCIFY_IGNORE_INDIRECT:
       passes += ['--pass-arg=asyncify-ignore-indirect']
+    if settings.ASYNCIFY_PROPAGATE_ADD:
+      passes += ['--pass-arg=asyncify-propagate-addlist']
     passes += ['--pass-arg=asyncify-imports@%s' % ','.join(settings.ASYNCIFY_IMPORTS)]
 
     # shell escaping can be confusing; try to emit useful warnings