One thread, one loop. See Part 1.

Single-threaded by default (one isolate). It appears concurrent via the event loop, which interleaves deferred callbacks — not by using multiple threads. True parallelism requires isolates.

One is high-priority and emptied completely.

The microtask queue and the event queue. The loop empties the entire microtask queue before processing even one event-queue item.

Sync code first; the Future callback is deferred.

1, 3, 2. 1 and 3 are synchronous; the Future callback runs only after main finishes.

One uses a constructor, one a function.

(a) Future(() {...}) / Future.delayed / timers / I/O add to the event queue. (b) scheduleMicrotask(() {...}) adds to the microtask queue (as does the continuation after an await).

Sync, then all microtasks, then events.

A, D, C, B. Synchronous (A,D) first; microtask (C) before event (B).

Think about the first suspension point.

"...until its first await." Code before the first await (validation, logging, kicking off requests) executes immediately in the current turn; only code after an await is deferred. So an async function is not fully "background".

f() runs to its first await, then defers the rest.

A, B, D, C. f() prints B synchronously up to await null, which defers print('C'); control returns and prints D, then the continuation prints C.

What event can't run while the loop runs?

Drawing each frame is itself an event. A long synchronous loop monopolizes the single thread, so the "paint frame" event never gets its turn — the UI can't update until the loop finishes.

Microtasks drain after every event too.

start, end, m0, e1, e2, m, e3. Sync first; then all microtasks (m0); then events one at a time, draining microtasks after each — so m (scheduled inside e2) runs before e3.

Microtasks outrank events, including frame draws.

Because microtasks always run before the next event (and frames are events), an endless stream of microtasks starves the event queue — frames never paint and the UI freezes. Prefer Future(...) for normal deferred work.

What is executing while you await?

No. It's concurrency on one thread — the thread interleaves tasks by parking work during I/O waits, but only one statement executes at any instant. It helps only when waiting, not computing. Parallelism needs isolates.

Think starvation and intent.

It cuts ahead of all events (including frames) and can starve the loop; you almost never need something to run before the next event. The safer default for "do this later" is Future(() {...}), which uses the event queue and lets frames/I-O interleave.

A buzzer, not the food. Part 2.

An object representing a value of type T that isn't available yet but will be produced — or will fail — at some later point.

Two states; completion has two flavors.

Uncompleted or completed; completion is either with a value (success) or with an error (failure). A future completes exactly once.

Future.delayed.

Future<int> answer() => Future.delayed(const Duration(seconds: 1), () => 42);
void main() => answer().then(print); // 42

getCount() is a future, not an int.

Await it inside an async main: Future<void> main() async { final count = await getCount(); print(count + 1); }. You can't do arithmetic on a Future.

Success / error / always.

.then = the success path; .catchError = catch; .whenComplete = finally (runs on success or error).

Dart flattens.

Future<String>, not Future<Future<String>>. Dart flattens returned futures — the chain waits for the inner future and adopts its value.

Future.wait.

final results = await Future.wait([a(), b()]); // ~2s, both overlap

Sequential await a(); await b(); would take ~4s.

All-or-nothing.

The returned future completes with an error as soon as any input future errors. (Use eagerError/individual catchError, or Future.any for "first to finish", depending on need.)

Completer.

Future<String> loadConfigFuture() {
  final c = Completer<String>();
  loadConfig((data) => c.complete(data));
  return c.future;
}

When completion isn't already a future.

When completion is driven by something that isn't a future — a callback API, a one-shot event/listener, a button tap, a native callback. You hand out completer.future now and fire complete/completeError later (exactly once).

Even an already-completed future schedules its .then.

b, then a 1. .then callbacks are always scheduled (as microtasks), so synchronous b prints first even though the future is already complete.

Microtask vs event queue.

Future.value(x) completes via the microtask queue (its .then runs sooner). Future(() => x) schedules the computation on the event queue (runs after pending microtasks and possibly other events). Different timing, same eventual value.

.timeout(...).

final r = await slow().timeout(const Duration(seconds: 2));
// throws TimeoutException if slow() takes longer; add onTimeout: for a fallback

It always returns one thing.

It always returns a Future. Even return 42; becomes a Future<int> to the caller. (Part 3)

Each .then → an await.

Future<String> load() async {
  final t = await fetchToken();
  final u = await fetchUser(t);
  return u.name;
}

No — with one modern exception.

No; await requires an async function body. (Top-level main can be async. Some setups also allow top-level await in scripts, but inside a function you must mark it async.)

Independent → overlap.

final results = await Future.wait(ids.map(fetch)); — ~1s instead of ~10s. Keep the sequential loop only if each fetch depends on the previous result.

No await, no catch.

riskyAsync() isn't awaited, so control leaves the try before it fails; the error becomes unhandled. Add await riskyAsync(); inside the try.

The widget may be gone after the await.

final d = await api.fetch();
if (!mounted) return;
setState(() => _data = d);

Synchronous contract.

build() must return a Widget now for the current frame; an async function returns a Future<Widget> the framework can't paint. Use FutureBuilder/StreamBuilder and create the future once (in initState/state mgmt).

forEach doesn't await.

forEach ignores the returned futures, so it fires them all without waiting and you can't catch their errors. Use a real for loop: for (final e in myList) { await save(e); } (or Future.wait(myList.map(save)) if independent).

await suspends until the future completes.

1, 2, 3. The await suspends main until the event-queue future runs (2), then resumes (3).

Deliberate fire-and-forget.

It marks a future as intentionally not awaited (silencing the unawaited_futures lint) so readers know it's deliberate — e.g. unawaited(analytics.log(...)). You still forgo error handling on it.

await the dependent; Future.wait the independents; finally.

try {
  final user = await fetchUser(id);            // dependent
  final r = await Future.wait([posts(user), friends(user)]); // independent
  return Dashboard(user, r[0], r[1]);
} finally { hideLoading(); }

Runs sync to first await.

A, B, D, C. t() prints B synchronously, defers C at the await, control returns and prints D, then C.

Each boundary hops the loop.

Every async/await boundary adds a Future wrapper and an event-loop hop (a microtask). For purely synchronous logic that's needless overhead — keep such functions synchronous.

Future.any.

final first = await Future.any([a(), b(), c()]); — completes with the first to finish (value or error).

Two related rules.

unawaited_futures (a future isn't awaited where one is expected) and discarded_futures (a future-returning call is used as if sync). Together they catch most "forgot await" bugs.

One value vs many over time. Part 4.

A Future delivers one value (or error) once; a Stream delivers a sequence of zero-to-many values over time, optionally with errors, ending in a "done" event.

data / ? / ?

Data events, error events, and a single done event.

Loop, then return after done.

Future<int> total(Stream<int> s) async {
  var sum = 0;
  await for (final v in s) sum += v;
  return sum;
}

Loop vs callbacks.

await for (loop-like; continue after done) when you process every event then move on; .listen() (onData/onError/onDone + a StreamSubscription) when you don't want to block and need pause/resume/cancel.

Cancel the subscription.

var n = 0; late StreamSubscription<int> sub;
sub = Stream.periodic(d, (i) => i).listen((v) { if (++n == 3) sub.cancel(); });

Listener count + replay.

Single-subscription: exactly one listener, buffers/waits so the listener sees the full ordered sequence. Broadcast: many listeners, fires regardless of listeners, latecomers miss earlier events.

Default stream type.

fromIterable is single-subscription — only one .listen. Use .asBroadcastStream() to allow multiple listeners (latecomers may miss events).

where → map → take.

Stream.fromIterable(List.generate(10, (i) => i + 1))
  .where((n) => n.isOdd).map((n) => n * n).take(3).listen(print); // 1,9,25

Leaks + dispose.

A live subscription keeps the stream and callback alive (memory leak; can cause "setState after dispose"). Cancel it in the State's dispose(): _sub?.cancel().

Returns a future per event.

asyncMap's transform returns a Future that's awaited per event (in order), enabling async work per item. map only supports synchronous transforms.

Terminal reducer.

final list = await stream.toList(); — a terminal operation that consumes the whole stream and returns a Future.

Buffering for future listeners.

Broadcast streams don't buffer for future listeners — they fire regardless of who's listening, so latecomers see only subsequent events. Single-subscription streams wait for their one listener and deliver the full sequence from the start.

initState listen, dispose cancel, mounted guard.

StreamSubscription<int>? _sub;
@override void initState() { super.initState();
  _sub = ticker.listen((v) { if (!mounted) return; setState(() => _v = v); }); }
@override void dispose() { _sub?.cancel(); super.dispose(); }

Read vs write. Part 5.

controller.stream (read end, for listeners) and controller.sink / add/addError/close (write end, to push events).

Don't forget close.

final c = StreamController<String>();
c.stream.listen(print, onDone: () => print('done'));
c.add('a'); c.add('b'); c.close();

Close & release.

close(). It signals completion (ends await for, fires onDone, tells StreamBuilder it's over) and releases the controller. Not calling it leaks.

Tie work to demand.

onListen fires when the first listener subscribes — start producing then. onCancel fires when the last leaves — clean up (timers, sockets). Don't produce before anyone listens.

Timer in onListen, cancel in onCancel.

late StreamController<int> c; Timer? t; var n = 0;
c = StreamController<int>(
  onListen: () => t = Timer.periodic(const Duration(milliseconds: 500), (_) => c.add(n++)),
  onCancel: () => t?.cancel());

Encapsulation.

The sink exposes only add/addError/close — producers can push but can't listen or tear down the controller. It enforces clean read/write separation (basis of event buses, BLoC).

.broadcast().

final c = StreamController<int>.broadcast();
c.stream.listen((v) => print('one $v'));
c.stream.listen((v) => print('two $v'));
c.add(9); // both get 9

Producer faster than consumer.

Backpressure = producing faster than the consumer can handle; undelivered events buffer (and can grow unbounded). onPause/onResume let a well-behaved producer stop generating when the consumer pauses and resume when it catches up.

Immediate re-entrant delivery.

A synchronous controller delivers events immediately inside the add() call, re-entering listener code at surprising times and breaking stream guarantees. Use the default (async) controller unless you have a specific, understood reason.

Hide the controller.

class EventBus<T> {
  final _c = StreamController<T>.broadcast();
  Stream<T> get events => _c.stream;
  void emit(T e) => _c.add(e);
  Future<void> dispose() => _c.close();
}

Iterable vs Stream. Part 6.

sync* returns an Iterable<T>; async* returns a Stream<T>. Both use yield.

Loop + yield.

Iterable<int> range(int s, int e) sync* { for (var i = s; i < e; i++) yield i; }

Emit + pause.

Emits one value and pauses the generator there; it resumes from that point when the consumer pulls the next value.

while(true) yield.

Iterable<int> evens() sync* { var n = 0; while (true) yield n += 2; }
print(evens().take(4).toList()); // [2,4,6,8] — never hangs

One vs all.

yield emits one value; yield* delegates to another iterable/stream, emitting all of its values in place (great for recursion; also more efficient than manual re-yielding).

yield* each inner.

Iterable<int> flatten(List<List<int>> n) sync* { for (final i in n) yield* i; }
// 1,2,3,4,5

Await inside the loop.

Stream<String> ticks() async* {
  for (var i = 0; i < 5; i++) { await Future.delayed(const Duration(milliseconds: 300)); yield 'tick'; }
}

Auto-closes when the loop ends.

Only computes what's pulled.

Generators run only far enough to produce requested values, pausing at each yield. take(n) pulls exactly n, so the infinite body never runs to completion. (A List would try to build everything and hang.)

Next yield acts like return.

The next time the body reaches a yield, it behaves like a return — the generator stops and the stream ends cleanly. The machinery handles cancellation for you.

sync* / controller / async*.

(a) sync* (pure lazy, no await); (b) StreamController.broadcast (external push, many listeners); (c) async* (your loop, awaits per page).

The golden rule. Part 7.

"...you await the failing future inside the try." No await, no catch.

Add one keyword.

try { await fetch(); } catch (e) { print('handled'); }.

Two methods.

.catchError() = catch; .whenComplete() = finally.

on Type catch.

try { await work(); }
on TimeoutException { ... }
on FormatException catch (e) { ... }
catch (e, s) { log(e, s); rethrow; }

Stack trace.

rethrow re-throws the same error with its original stack trace; throw e resets the trace to the current line, hiding the true origin.

handleError.

Stream.fromIterable([2,0,4]).map((n) => 100 ~/ n)
  .handleError((e) => print('skip $e')).listen((v) => print('ok $v'));

It's thrown out.

The error is thrown out of await for, terminating the loop (it lands in a surrounding try/catch). To keep consuming, use .listen(onError:) or .handleError().

Count + ending.

A future fails at most once and is settled. A stream can emit multiple error events and an error doesn't necessarily end it (cancelOnError). So you choose stop-on-error (await for / cancelOnError: true) vs continue (onError/handleError).

Unhandled async error.

The future fails on a later turn, after the sync try exited — it's an unhandled async error. Locally: await/catchError it. Globally: wrap in runZonedGuarded (or set FlutterError.onError/PlatformDispatcher.instance.onError).

Stop after first error?

It decides whether the subscription is cancelled after the first error event. Default is false — the stream keeps delivering events after an error.

catch + throw domain error.

try { return await http.get(url); }
on SocketException catch (e) { throw AppError('Network down: $e'); }

Boundaries are where you convert technical errors into meaningful ones.

finally / whenComplete.

In finally (or .whenComplete). It runs regardless of success, exception, or rethrow, guaranteeing resources are released and UI state is reset on every path.

CPU vs I/O. Part 8.

True parallelism for CPU-bound work. async/await only helps while waiting on I/O; a heavy computation blocks the single thread, so it must run on another thread — an isolate.

They don't.

They don't share memory — each has its own memory and event loop. They communicate only via copied messages over SendPort/ReceivePort. No shared state → no locks, no data races.

Isolate.run.

final r = await Isolate.run(() => sumTo(100000000));

No new thread.

async doesn't add a thread; it only interleaves while waiting. A CPU loop never waits and never yields, so the event loop (including frame drawing) stays blocked. Move it to an isolate.

compute with a top-level fn.

List<Item> _parse(String b) => (jsonDecode(b) as List).map(Item.fromJson).toList();
final items = await compute(_parse, response.body);

Not a closure.

It must be top-level or static (single message arg). Closures capturing local state can't be sent to another isolate.

One-shot vs long-lived.

Isolate.run for one-shot work (it hides port wiring and auto-shuts-down). Isolate.spawn + ports for long-lived workers handling many messages.

Exchange SendPorts.

Main creates a ReceivePort and passes its sendPort on spawn; the worker creates its own ReceivePort and sends its sendPort back as the first message. Now each holds the other's SendPort → two-way comms.

Native resources.

The open Socket can't be sent (native resource bound to the origin isolate). The others are sendable. (Also non-sendable: ReceivePort, Pointer, DynamicLibrary, finalizers.)

Overhead vs work.

When the work is small relative to spawn + message-copy overhead — the isolate can be slower than inline. Isolates pay off only when the computation clearly dwarfs that cost.

Context across async gaps. Part 9.

An execution context that stays attached to your code across asynchronous gaps, so behaviors like error handling, print, and context values apply to all callbacks that code later schedules.

runZonedGuarded.

runZonedGuarded(() { Future(() => throw 'oops'); },
  (e, s) => print('reported: $e'));

Sync vs async scope.

try/catch only guards code in the current synchronous call stack. Async callbacks run later on fresh stacks with no try/catch. A zone stays attached to all callbacks scheduled within it, so its handler still applies whenever they throw.

zone-local values.

runZoned(() => deepHelper(), zoneValues: {#requestId: 'r1'});
// deepHelper: print(Zone.current[#requestId]);

Framework + async.

Flutter runs your app in a zone so no async error disappears. Wire FlutterError.onError (framework/synchronous errors) and runZonedGuarded's onError (or PlatformDispatcher.instance.onError) for uncaught async errors — both routed to your reporter (Crashlytics/Sentry).

Future<T> retry<T>(Future<T> Function() task, {int attempts = 3}) async {
  for (var i = 1; ; i++) {
    try {
      return await task();
    } catch (e) {
      if (i >= attempts) rethrow;            // out of attempts → propagate
      await Future.delayed(Duration(milliseconds: 200 * i)); // backoff
    }
  }
}

Combines async/await (Part 3), error handling + rethrow (Part 7), and Future.delayed (Part 2).

Future<List<R>> mapPooled<T, R>(
    List<T> items, Future<R> Function(T) worker, {int n = 4}) async {
  final results = List<R?>.filled(items.length, null);
  var index = 0;

  Future<void> runner() async {
    while (true) {
      final i = index++;          // claim the next item
      if (i >= items.length) return;
      results[i] = await worker(items[i]);
    }
  }

  await Future.wait(List.generate(n, (_) => runner())); // n workers in flight
  return results.cast<R>();
}

Future.wait (Part 2) runs n "runner" loops concurrently; each pulls from a shared index. A real-world throttle.

Stream<T> debounce<T>(Stream<T> source, Duration d) {
  late StreamController<T> controller;
  Timer? timer;
  controller = StreamController<T>(
    onListen: () {
      source.listen((value) {
        timer?.cancel();                       // reset the quiet timer
        timer = Timer(d, () => controller.add(value));
      }, onError: controller.addError, onDone: () {
        timer?.cancel();
        controller.close();
      });
    },
    onCancel: () => timer?.cancel(),
  );
  return controller.stream;
}

Uses StreamController lifecycle (Part 5) and a Timer. Each new event cancels the pending emit; only a 300ms gap lets one through.

Stream<T> merge<T>(Stream<T> a, Stream<T> b) async* {
  final controller = StreamController<T>();
  final subs = [a.listen(controller.add), b.listen(controller.add)];
  var open = 2;
  for (final s in subs) {
    s.onDone(() { if (--open == 0) controller.close(); });
  }
  yield* controller.stream;                    // re-emit the merged stream
}

Combines StreamController (Part 5) with async* + yield* (Part 6). (Production code: use package:rxdart's MergeStream.)

Future<T> withTimeout<T>(Future<T> f, Duration d) {
  return f.timeout(d); // built-in; throws TimeoutException on expiry
}
// Manual version with Completer, for understanding:
Future<T> manualTimeout<T>(Future<T> f, Duration d) {
  final c = Completer<T>();
  final timer = Timer(d, () {
    if (!c.isCompleted) c.completeError(TimeoutException('timed out', d));
  });
  f.then((v) { if (!c.isCompleted) c.complete(v); },
         onError: (e, s) { if (!c.isCompleted) c.completeError(e, s); })
   .whenComplete(timer.cancel);
  return c.future;
}

The manual version shows Completer (Part 2) racing a Timer — isCompleted guards the "complete once" rule.

Stream<Item> allItems(Future<List<Item>> Function(int page) getPage) async* {
  for (var page = 1; ; page++) {
    final batch = await getPage(page);   // await between yields
    if (batch.isEmpty) return;           // closes the stream
    for (final item in batch) yield item;
  }
}
// Consumer pulls only 30 → fetching stops once 30 are yielded:
await for (final item in allItems(api.getPage).take(30)) { render(item); }

Pure async* laziness (Part 6) — take(30) cancels the generator, so no extra pages are fetched.

Future<Result> parseHeavy(String raw) async {
  try {
    return await Isolate.run(() => expensiveParse(raw)); // another thread
  } catch (e, s) {
    reporter.record(e, s);  // log/report
    rethrow;                // let caller/UI react
  }
}

Isolate.run (Part 8) for parallelism; try/catch + rethrow (Part 7) because errors thrown inside the isolate propagate back through the returned future.

1
6
4
5
2
3

1,6 sync. Microtask queue drains next: scheduleMicrotask→4, then Future.value().then→5 (already-complete future schedules its .then as a microtask). Then the event queue: Future(...)→2, whose .then (3) is queued as a microtask and runs immediately after that event. Tests Sections A & B together.

class Once<T> {
  final Future<T> Function() _init;
  Future<T>? _future;
  Once(this._init);

  Future<T> get value => _future ??= _init(); // start once; reuse the future
}

// Usage: every caller awaits the SAME in-flight future, so _init runs once.
final config = Once(() => loadConfigFromDisk());

The ??= ensures _init() is invoked only on the first access; concurrent callers all receive the same Future (no duplicate work). Connects to "a future completes once" (Part 2).

import 'dart:async';
import 'dart:isolate';

class JobResult {
  final int id;
  final Object? value;
  final Object? error;
  JobResult.ok(this.id, this.value) : error = null;
  JobResult.fail(this.id, this.error) : value = null;
}

class JobRunner {
  final _results = StreamController<JobResult>.broadcast(); // (3) results out
  final _queue = StreamController<MapEntry<int, int>>();    // incoming jobs
  late final StreamSubscription _sub;
  var _nextId = 0;

  JobRunner() {
    // (2) process sequentially: await each job before taking the next.
    _sub = _queue.stream.listen((entry) async {
      final id = entry.key, input = entry.value;
      try {
        final out = await Isolate.run(() => _heavy(input)); // (1)+(2) off-thread
        _results.add(JobResult.ok(id, out));
      } catch (e) {
        _results.add(JobResult.fail(id, e));                // (4) report, keep going
      }
    });
  }

  Stream<JobResult> get results => _results.stream;

  int submit(int input) {
    final id = _nextId++;
    _queue.add(MapEntry(id, input));
    return id; // caller can match results by id
  }

  Future<void> dispose() async {                            // (5) cleanup
    await _sub.cancel();
    await _queue.close();
    await _results.close();
  }

  static int _heavy(int n) {                                 // top-level-ish work
    var t = 0;
    for (var i = 0; i < n; i++) t += i;
    return t;
  }
}

This single class exercises the whole series: a StreamController queue (Part 5), sequential await processing so jobs run in order (Part 3), Isolate.run for parallel compute (Part 8), a broadcast results stream (Part 4), try/catch that reports without killing the queue (Part 7), and disciplined dispose cleanup. If you can build and explain this, you've mastered async Dart.