sema-docs 1.23.0

Canonical structured documentation for Sema builtins/special forms; powers LSP hover/completion and REPL apropos
Documentation
---
name: "async"
module: "special-forms"
syntax: "(async body ...)"
---

Spawn the body expressions as an asynchronous task and return a promise for its result. The body is wrapped in a zero-argument thunk and handed to `async/spawn`; it runs cooperatively on the VM scheduler when driven by `await`, `async/run`, or `async/all`.

```sema
(define p (async (+ 1 2)))
(await p)   ; => 3
```

Multiple async tasks can run concurrently. They interleave at yield points such as channel operations, `await`, or `sleep`.

```sema
(let ((p1 (async (* 3 3)))
      (p2 (async (* 4 4))))
  (+ (await p1) (await p2)))   ; => 25
```

The promise returned by `async` can be passed around, stored in data structures, or awaited multiple times. If the body completes normally, the promise resolves to the last expression's value. If the body throws an error, the promise rejects and the error is re-raised when the promise is awaited.

```sema
(define slow (async
               (sleep 100)
               "done"))
(await slow)   ; => "done"
```