What is await* (with asterisk)?

What is await* (with asterisk) in Motoko?

In Motoko, await* (with an asterisk) is a keyword used to execute a delayed asynchronous computation that was previously created using the async* keyword.

The await* keyword differs from the regular await keyword in that it only commits state and suspends execution when necessary in the await*-ed computation, not necessarily at the await* itself. This helps to avoid the resource consumption and latency associated with regular async/await keywords.

Please clarify: await* commits state and suspends execution:

  • at arbitrary points
  • at await* and any other points
  • at a subset of awaits?

Also, please help me to understand usual use cases of await*. How to decide should I use await or await*?

Motoko tutorial seems to be silent about awake*. Could you point me a tutorial?

The async* and corresponding await* constructs provide an efficient way to abstract asynchronous code into reusable functions. When calling a local function that returns a proper async type, committing state and suspending execution occur with each await of its result. This can be an undesirable and inefficient way of handling asynchronous code. By using async* and await*, the generator-based approach can optimize performance by only suspending and resuming execution when necessary, resulting in more efficient and cleaner code.

The locations where both tentative state changes and message sends become permanently binding are as follows:

  • When a shared function produces a result, resulting in an implicit exit.
  • When an explicit exit occurs through the use of return or throw expressions.
  • When explicit await expressions are used.