Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 36 ยท Memory and Concurrency

Async and Await in Nim

Learn Nim's asyncdispatch module: async procs, await, futures, running several tasks at once with all, and how an event loop works, with a C stand-in scheduler.

Waiting is slow: a network reply or a file read takes milliseconds while the CPU could do millions of operations. Asynchronous programming lets one thread start an operation, move on to other work, and come back when the result is ready. Nim provides this in the standard library module std/asyncdispatch, with async and await keywords that look like ordinary code.

The real compiler is not available here, so the Nim code is read-only. The C stand-ins build a tiny event loop to show what is going on.

async procs and futures

An {.async.} proc returns a Future[T]: a promise of a value that will exist later. await suspends the current async proc until the future completes, letting the dispatcher run other tasks meanwhile.

NIM
import std/asyncdispatch

proc slowDouble(x: int): Future[int] {.async.} =
  await sleepAsync(100)       # yields to the event loop for 100 ms
  return x * 2

proc main() {.async.} =
  let a = await slowDouble(5)
  echo a                      # 10

waitFor main()                # run the loop until main finishes

waitFor drives the event loop from ordinary (non-async) code, typically in your program's entry point. An async proc must be awaited or its failures can be lost; discard a future on purpose with asyncCheck, which re-raises errors.

Running tasks together

Awaiting one after another is sequential. To overlap waits, start the futures first and then wait for all of them.

NIM
proc main() {.async.} =
  let f1 = slowDouble(1)
  let f2 = slowDouble(2)
  let f3 = slowDouble(3)
  let results = await all(f1, f2, f3)   # about 100 ms in total, not 300
  echo results                          # @[2, 4, 6]

All three sleeps run concurrently on one thread; the total time is about one sleep, not three.

How the event loop works

An async proc is compiled into a state machine: each await splits it into steps, and the proc remembers which step to resume. The dispatcher keeps a list of waiting tasks and runs whichever is ready. This stand-in does that by hand with two tasks that take turns:

C C stand-in: cooperative tasks on one thread

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

The output interleaves A and B because each task gives up control at its await point. No second thread exists, so no locks are needed.

A timer queue

Real loops also wait for timers. This stand-in orders tasks by wake-up time and "sleeps" by moving a fake clock, which is what sleepAsync registers with the dispatcher:

C C stand-in: timers ordered by wake-up time

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

Errors and timeouts

try/except works around await: an exception inside the awaited future is raised at the await. Use withTimeout(fut, ms) to give up waiting, and cancel if your Nim version supports it for the future in question.

NIM
proc main() {.async.} =
  try:
    let ok = await withTimeout(slowDouble(1), 10)
    echo ok               # false: the timeout fired first
  except CatchableError as e:
    echo "failed: ", e.msg

When to use async

Async shines for many connections that mostly wait: web servers (std/asynchttpserver), clients (std/httpclient's async client) and sockets (std/asyncnet). It does not speed up CPU-bound work; one long calculation blocks every other task. For that, use threads and channels. The two combine: run heavy work on a thread and await its result.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does an async proc return?

    async procs return Future[T], completed later.
  2. 2. What does waitFor do?

    waitFor drives the dispatcher from non-async code.
  3. 3. How do you overlap three awaits?

    Starting first and waiting together lets their waits overlap.
  4. 4. Why does one long CPU loop hurt an async program?

    Cooperative tasks only switch at await points.

Summary

  • {.async.} procs return futures; await suspends without blocking the thread.
  • waitFor runs the loop; all overlaps tasks.
  • Async procs are compiled to state machines scheduled by a dispatcher.
  • Use async for waiting, threads for computing.

Next: Calling C from Nim