Replace old fastcomp asyncify docs with docs for the new wasm backend (#9017)

Author: kripken

site/source/docs/porting/asyncify.rst

@@ -4,123 +4,222 @@
 Asyncify
 ========================
 
-In general, you want to make your code as asynchronous-friendly as possible, e.g. by never calling sleep, having a single main loop and so on.
+Asyncify lets **synchronous** C or C++ code interact with **asynchronous**
+JavaScript. This allows things like:
 
-Sometimes refactoring a codebase with this in mind isn't feasible, so there are a couple of alternatives (each with downsides). Asyncify is covered here.
+ * A synchronous call in C that yields to the event loop, which
+   allows browser events to be handled.
+ * A synchronous call in C that waits for an asynchronous operation in JS to
+   complete.
 
-**Asyncify is experimental, and not recommended. See https://kripken.github.io/emscripten-site/docs/porting/emterpreter.html for a more recent option with similar functionality, that is currently supported.**
+Asyncify automatically transforms your compiled code into a form that can be
+paused and resumed, and handles pausing and resuming for you, so that it is
+asynchronous (hence the name "Asyncify") even though you wrote it in a normal
+synchronous way.
 
-``ASYNCIFY`` allows you to use some asynchronous function in C, through several transformation of LLVM IR.
+See the
+`Asyncify introduction blogpost <https://kripken.github.io/blog/wasm/2019/07/16/asyncify.html>`_
+for general background and details of how it works internally. The following
+expands on the Emscripten examples from that post.
 
-Intro
-=====
+.. note:: This post talks about Asyncify using the new LLVM wasm backend.
+          There is also an older Asyncify implementation for the old fastcomp
+          backend. The two algorithms and implementations are entirely separate,
+          so if you are using fastcomp, these docs may not be accurate - you
+          should upgrade to the wasm backend and new Asyncify!
 
-If you call ``sleep()`` in C/C++, what kind of JavaScript code would you expect emscripten to produce?
+Sleeping / yielding to the event loop
+#####################################
 
-::
+Let's begin with the example from that blogpost:
+
+.. code-block:: cpp
 
-    // test.c
+    // example.cpp
+    #include <emscripten.h>
     #include <stdio.h>
-    #include <unistd.h>
+
+    // start_timer(): call JS to set an async timer for 500ms
+    EM_JS(void, start_timer, (), {
+      Module.timer = false;
+      setTimeout(function() {
+        Module.timer = true;
+      }, 500);
+    });
+
+    // check_timer(): check if that timer occurred
+    EM_JS(bool, check_timer, (), {
+      return Module.timer;
+    });
+
     int main() {
-      int i = 100;
-      printf("Hello\n");
-      sleep(1);
-      printf("World %d!\n");
-      return 0;
+      start_timer();
+      // Continuously loop while synchronously polling for the timer.
+      while (1) {
+        if (check_timer()) {
+          printf("timer happened!\n");
+          return 0;
+        }
+        printf("sleeping...\n");
+        emscripten_sleep(100);
+      }
     }
 
-Note that we cannot implement ``sleep`` like this::
+You can compile that with
 
-    function sleep(ms) {
-      var t = Date.now() + ms;
-      while(Date.now() < t) ;
-    }
+::
 
-because this would block the JavaScript engine, such that pending events cannot be processed.
+    emcc -O3 example.cpp -s ASYNCIFY
 
+.. note:: It's very important to optimize (``-O3`` here) when using Asyncify, as
+          unoptimized builds are very large.
 
-A hand written counterpart in JavaScript would be
+And you can run it with
 
 ::
 
-    function main() {
-      var i = 100;
-      console.log('Hello');
-      setTimeout(function() {
-        console.log('World ' + i + '!');
-        async_return_value = 0;
-      }, 1000);
-    }
+    nodejs a.out.js
 
-Specifically, a number of aspects should be taken into consideration:
- - Split the function when an async function is called, and the second function should be registered as the callback for the async function
- - Any function that calls an async function also becomes an async function.
- - Keep all local variables available to the callback
- - Closure cannot be used in order to make asm.js validated code.
- - Take care of loops and branches
- - Make the return value available to the callee
- - Some functions could be both sync or async, depending on the input.
+You should then see something like this:
 
-And the ``ASYNCIFY`` option does all above automatically, through a number of transformations on LLVM IR.
+::
 
+    sleeping...
+    sleeping...
+    sleeping...
+    sleeping...
+    sleeping...
+    timer happened!
 
-Usage
-=====
+The code is written with a straightforward loop, which does not exit while
+it is running, which normally would not allow async events to be handled by the
+browser. With Asyncify, those sleeps actually yield to the browser's main event
+loop, and the timer can happen!
 
-Call ``emscripten_sleep()`` whenever you need to pause the program, and add ``-s ASYNCIFY=1`` to emscripten.
+Making async Web APIs behave as if they were synchronous
+########################################################
 
-Sometimes it's a good replacement of ``emscripten_set_main_loop``, you may replace all ``sleep``-alike functions with ``emscripten_sleep``, instead of refactoring the whole main loop.
+Aside from ``emscripten_sleep`` and the other standard sync APIs Asyncify
+supports, you can also add your own functions. To do so, you must create a JS
+function that is called from wasm (since Emscripten controls pausing and
+resuming the wasm from the JS runtime). One way to do that is with a JS library
+function; another is to use ``EM_JS``, which we'll use in this next example:
 
-Also ``emscripten_sleep(1)`` can be used to 'interrupt' your code, such that the JavaScript engine can do the rendering and process events.
+.. code-block:: cpp
 
-Extensions
-==========
+    // example.c
+    #include <emscripten.h>
+    #include <stdio.h>
 
-It is possible to implement more new async functions that appears to be sync in C.
+    EM_JS(void, do_fetch, (), {
+      Asyncify.handleSleep(function(wakeUp) {
+        out("waiting for a fetch");
+        fetch("a.html").then(response => {
+          out("got the fetch response");
+          // (normally you would do something with the fetch here)
+          wakeUp();
+        });
+      });
+    });
 
-- Implement the function normally in a JavaScript library, suppose the function name is ``func``.
-- Add ``func`` into ``ASYNCIFY_FUNCTIONS``
-- When ``func`` is called and finished, the program will NOT continue, instead it just save the context and exit.
-- Call ``_emscripten_async_resume`` when you want to resume the program, usually in the callback functions of some async calls.
+    int main() {
+      puts("before");
+      do_fetch();
+      puts("after");
+    }
 
-Please read ``src/library_async.js`` for details.
 
-Limitations
-===========
+The async operation happens in the ``EM_JS`` function ``do_fetch()``, which
+calls ``Asyncify.handleSleep``. It gives that function the code to be run, and
+gets a ``wakeUp`` function that it calls in the asynchronous future at the right
+time. After we call ``wakeUp()`` the compiled C code resumes normally.
 
-Code size increase should be expected, depending on the specific input.
-``-Os`` (or ``-Oz`` for linking) is recommended when ``ASYNCIFY`` is turned on.
-E.g. usually the following loop is expanded to speed up::
+In this example the async operation is a ``fetch``, which means we need to wait
+for a Promise. While that is async, note how the C code in ``main()`` is
+completely synchronous!
 
-    for(int i = 0; i < 3; ++i) {
-      // do something
-      emscripten_sleep(1000);
-      // do something else
-    }
+To run this example, first compile it with
 
-However by expanding the loop, two more async calls are introduced, such that more callback functions will be produced during the asyncify transformation.
+::
+
+    ./emcc example.c -O3 -o a.html -s ASYNCIFY -s 'ASYNCIFY_IMPORTS=["do_fetch"]'
 
-**Asyncify can make performance much slower, if it ends up splitting a function which you need to be fast.**
+Note that 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.
 
-``setjmp/longjmp`` and C++ exception are not working well when there are async function calls in the scope, but they still work when there's no async calls. E.g.
+To run this, you must run a webserver (like say ``python -m SimpleHTTPServer``)
+and then browse to ``http://localhost:8000/a.html`` (the URL may depend on the
+port number in the server). You will see something like this:
 
 ::
 
-    try {
-      // do something
-      if(error) throw 0; // works
-      emscripten_sleep(1000);
-      // do something else
-      if(error) throw 0; // does not work
-    }
+    before
+    waiting for a fetch
+    got the fetch response
+    after
+
+That shows that the C code only continued to execute after the async JS
+completed.
+
+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. The key thing is to add such methods
+to ``ASYNCIFY_IMPORTS``, regardless of whether the JS function is from a JS
+library or ``EM_JS``. 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.
+
+The ``ASYNCIFY_IMPORTS`` list must contain **all** relevant imports, not just
+ones you add yourself, so it must contain things like ``emscripten_sleep()``
+if you call them (by default the list will contain them, so you must only add
+them if you change the list).
+
+You can also set ``ASYNCIFY_IMPORTS`` to ``[]`` (an empty list). In that case,
+Asyncify will assume that any import may do an async operation. This will result
+in larger and slower code in most cases, but can be useful during debugging or
+development.
+
+Potential problems
+##################
+
+Stack overflows
+***************
+
+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.
+
+Reentrancy
+**********
+
+While waiting on an asynchronous operation browser events can happen. That
+is often the point of using Asyncify, but unexpected events can happen too.
+For example, if you just want to pause for 100ms then you can call
+``emscripten_sleep(100)``, but if you have any event listeners, say for a
+keypress, then if a key is pressed the handler will fire. If that handler
+calls into compiled code, then it can be confusing, since it starts to look
+like coroutines or multithreading, with multiple executions interleaved.
+
+It is *not* safe to start an async operation while another is already running.
+The first must complete before the second begins.
+
+Such interleaving may also break assumptions in your codebase. For example,
+if a function uses a global and assumes nothing else can modify it until it
+returns, but if that function sleeps and an event causes other code to
+change that global, then bad things can happen.
 
-Currently all function pointer calls are considered as aync, and some functions might be recognized as async incorrectly. This can be corrected by manually setting the ``ASYNCIFY_WHITELIST`` option.
+Migrating from older APIs
+#########################
 
+If you have code using the Emterpreter-Async API, or the old Asyncify, then the
+new API is somewhat different, and you may need some minor changes:
 
-Other possible implementations
-==============================
+ * The Emterpreter has "yielding" as a concept, but it isn't needed in Asyncify.
+   You can replace ``emscripten_sleep_with_yield()`` calls with ``emscripten_sleep()``.
+ * The JS API is different. See notes above on ``Asyncify.handleSleep()``, and
+   see ``src/library_async.js`` for more examples.
 
- - Closures (breaking asm.js)
- - Generators (too slow currently)
- - Blocking message (in workers)