[ASYNCIFY] Document new __async decorator. NFC (emscripten-core#26130)

Author: sbc100

ChangeLog.md

@@ -31,6 +31,9 @@ See docs/process.md for more on how version tagging works.
 - Embind now supports the JS iterable protocol on bound classes via
   `class_<T>::iterable()`. `register_vector` uses this so bound `std::vector`
   works with `for...of`/`Array.from()`/spread. (#25993)
+- ASYNCIFY/JSPI functions in JS library files can now be marked as `__async:
+  'auto'`, which allows async JS function to be used unmodified with
+  ASYNCIFY/JSPI. (#26130, #26019)
 
 4.0.23 - 01/10/26
 -----------------

site/source/docs/porting/asyncify.rst

@@ -12,7 +12,6 @@ C++ code interact with **asynchronous** JavaScript. This allows things like:
  * A synchronous call in C that waits for an asynchronous operation in JS to
    complete.
 
-
 In general the two options are very similar, but rely on different underlying
 mechanisms to work.
 
@@ -162,6 +161,45 @@ You will see something like this:
 That shows that the C code only continued to execute after the async JS
 completed.
 
+Marking JS library functions as async
+#####################################
+
+If you mark a JS library function as async using the ``__async`` decorator then
+the compiler will take a care of all the details of using the ``Asyncify`` API
+for you.  The function will also automatically be incldued in
+:ref:`ASYNCIFY_IMPORTS`.  All you need to do is write normal async JS function
+(either using the explict ``async`` JS keyword or returning a ``Promise``
+object).  For example:
+
+.. code-block:: js
+
+   addToLibrary({
+     fetch_v1__async: 'auto',
+     fetch_v2: async (url) => {
+       const response = await fetch(UTF8ToString(url);
+       const json_data = await response.json();
+       return stringToNewUTF8(json_data);
+     },
+
+     fetch_v2__async: 'auto',
+     fetch_v2: (url) => {
+       return fetch(UTF8ToString(url))
+         .then((rsp) => response.json())
+         .then((json_data) => stringToNewUTF8(json_data));
+     },
+   });
+
+This JS library file contains two JS functions (``fetch_v1`` and ``fetch_v2``)
+which do exactly the same thing, one using the JS ``async`` keyword and one
+using promise chaining.  They are both marked as ``__async: 'auto'`` which means
+they will automatically suspend Wasm executation when called and resume when the
+resulting promise resolves.
+
+You can use ``__async: 1`` if you just want to include the function in
+:ref:`ASYNCIFY_IMPORTS` or ``__async: 'auto'`` if you also want the function to
+wrapper in ``Asyncify.handleAsync``.
+
+
 Ways to use Asyncify APIs in older engines
 ##########################################
 
@@ -184,8 +222,9 @@ directly with ``EM_JS`` and ``Asyncify.handleAsync`` instead:
 
 When using this form, the compiler doesn't statically know that ``do_fetch`` is
 asynchronous anymore. Instead, you must tell the compiler that ``do_fetch()``
-can do an asynchronous operation using ``ASYNCIFY_IMPORTS``, otherwise it won't
-instrument the code to allow pausing and resuming (see more details later down):
+can do an asynchronous operation using :ref:`ASYNCIFY_IMPORTS`, otherwise it
+won't instrument the code to allow pausing and resuming (see more details later
+down):
 
 ::
 
@@ -219,10 +258,10 @@ More on ``ASYNCIFY_IMPORTS``
 
 As in the above example, you can add JS functions that do an async operation but
 look synchronous from the perspective of C. If you don't use ``EM_ASYNC_JS``,
-it's vital to add such methods to ``ASYNCIFY_IMPORTS``. That list of imports is
-the list of imports to the Wasm module that the Asyncify instrumentation must be
-aware of. Giving it that list tells it that all other JS calls will **not** do
-an async operation, which lets it not add overhead where it isn't needed.
+it's vital to add such methods to :ref:`ASYNCIFY_IMPORTS`. That list of imports
+is the list of imports to the Wasm module that the Asyncify instrumentation must
+be aware of. Giving it that list tells it that all other JS calls will **not**
+do an async operation, which lets it not add overhead where it isn't needed.
 
 .. note:: If the import is not inside ``env`` the full path must be specified, for example, ``ASYNCIFY_IMPORTS=wasi_snapshot_preview1.fd_write``
 
@@ -231,7 +270,7 @@ Asyncify with Dynamic Linking
 
 If you want to use Asyncify in dynamic libraries, those methods which are imported
 from other linked modules (and that will be on the stack in an async operation)
-should be listed in ``ASYNCIFY_IMPORTS``.
+should be listed in :ref:`ASYNCIFY_IMPORTS`.
 
 .. code-block:: cpp
 
@@ -262,8 +301,8 @@ linking manner:
     }
 
 In the main module, the compiler doesn’t statically know that ``sleep_for_seconds`` is
-asynchronous. Therefore, you must add ``sleep_for_seconds`` to the ``ASYNCIFY_IMPORTS``
-list.
+asynchronous. Therefore, you must add ``sleep_for_seconds`` to the
+:ref:`ASYNCIFY_IMPORTS` list.
 
 ::
 
@@ -281,9 +320,9 @@ and want to ``await`` a dynamically retrieved ``Promise``, you can call an
     val my_object = /* ... */;
     val result = my_object.call<val>("someAsyncMethod").await();
 
-In this case you don't need to worry about ``ASYNCIFY_IMPORTS`` or
-``JSPI_IMPORTS``, since it's an internal implementation detail of ``val::await``
-and Emscripten takes care of it automatically.
+In this case you don't need to worry about :ref:`ASYNCIFY_IMPORTS` or
+:ref:`JSPI_IMPORTS`, since it's an internal implementation detail of
+``val::await`` and Emscripten takes care of it automatically.
 
 Note that when using Embind exports, Asyncify and JSPI behave differently. When
 Asyncify is used with Embind and the code is invoked from JavaScript, then the
@@ -373,9 +412,9 @@ Differences Between Asyncify and JSPI
 Besides using different underlying mechanisms, Asyncify and JSPI also handle
 async imports and exports differently. Asyncify will automatically determine
 what exports will become async based on what could potentially call an
-an async import (``ASYNCIFY_IMPORTS``). However, with JSPI, the async imports
-and exports must be explicitly set using ``JSPI_IMPORTS`` and ``JSPI_EXPORTS``
-settings.
+an async import (:ref:`ASYNCIFY_IMPORTS`). However, with JSPI, the async imports
+and exports must be explicitly set using :ref:`JSPI_IMPORTS` and
+:ref:`JSPI_EXPORTS` settings.
 
 .. note:: ``<JSPI/ASYNCIFY>_IMPORTS`` and ``JSPI_EXPORTS`` aren't needed when
           using various helpers mentioned above such as: ``EM_ASYNC_JS``,
@@ -394,39 +433,39 @@ code to allow unwinding and rewinding. That overhead is usually not extreme,
 something like 50% or so. Asyncify achieves that by doing a whole-program
 analysis to find functions need to be instrumented and which do not -
 basically, which can call something that reaches one of
-``ASYNCIFY_IMPORTS``. That analysis avoids a lot of unnecessary overhead,
+:ref:`ASYNCIFY_IMPORTS`. That analysis avoids a lot of unnecessary overhead,
 however, it is limited by **indirect calls**, since it can't tell where
 they go - it could be anything in the function table (with the same type).
 
 If you know that indirect calls are never on the stack when unwinding, then
 you can tell Asyncify to ignore indirect calls using
-``ASYNCIFY_IGNORE_INDIRECT``.
+:ref:`ASYNCIFY_IGNORE_INDIRECT`.
 
 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.
+* :ref:`ASYNCIFY_REMOVE` is a list of functions that do not unwind the stack.
   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
+* :ref:`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. If the ``ASYNCIFY_PROPAGATE_ADD`` setting is
+  if you use :ref:`ASYNCIFY_IGNORE_INDIRECT` but want to also mark some additional
+  functions that need to unwind. If the :ref:`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
+  analysis. If :ref:`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
+* :ref:`ASYNCIFY_ONLY` is a list of the **only** functions that can unwind
   the stack. Asyncify will instrument exactly those and no others.
 
-You can enable the ``ASYNCIFY_ADVISE`` setting, which will tell the compiler to
+You can enable the :ref:`ASYNCIFY_ADVISE` setting, which will tell the compiler to
 output which functions it is currently instrumenting and why. You can then
-determine whether you should add any functions to ``ASYNCIFY_REMOVE`` or
-whether it would be safe to enable ``ASYNCIFY_IGNORE_INDIRECT``. Note that this
+determine whether you should add any functions to :ref:`ASYNCIFY_REMOVE` or
+whether it would be safe to enable :ref:`ASYNCIFY_IGNORE_INDIRECT`. Note that this
 phase of the compiler happens after many optimization phases, and several
 functions maybe be inlined already. To be safe, run it with `-O0`.
 
-For more details see ``settings.js``. Note that the manual settings
+For more details see :ref:`settings-reference`. Note that the manual settings
 mentioned here are error-prone - if you don't get things exactly right,
 your application can break. If you don't absolutely need maximal performance,
 it's usually ok to use the defaults.
@@ -439,7 +478,7 @@ Stack overflows (Asyncify)
 
 If you see an exception thrown from an ``asyncify_*`` API, then it may be
 a stack overflow. You can increase the stack size with the
-``ASYNCIFY_STACK_SIZE`` option.
+:ref:`ASYNCIFY_STACK_SIZE` option.
 
 Reentrancy
 **********
@@ -467,7 +506,7 @@ The examples above show `wakeUp()` being called from JS (after a callback,
 typically), and without any compiled code on the stack. If there *were* compiled
 code on the stack, then that could interfere with properly rewinding and
 resuming execution, in confusing ways, and therefore an assertion will be
-thrown in a build with ``ASSERTIONS``.
+thrown in a build with :ref:`ASSERTIONS`.
 
 (Specifically, the problem there is that while rewinding will work properly,
 if you later unwind again, that unwinding will also unwind through that extra