Futures and async/await

One thread, an event loop

A Dart program (and each Flutter app's UI) runs your code on a single thread with an event loop. The event loop is like a to-do list: it takes the next event (a tap, a timer, a network response), runs the code for it, then takes the next. If one piece of code takes too long, everything else waits, and in Flutter the screen freezes. So slow operations like network calls, file reads and timers are asynchronous: they start, and their result arrives later as a new event.

Futures

Future<int> fetchBalance() {
  return Future.delayed(const Duration(seconds: 1), () => 2500);   // pretend network call
}

void main() {
  print('Loading...');
  fetchBalance().then((b) => print('Balance: Rs $b'));
  print('This line runs before the balance arrives');
}

A Future is in one of three states: uncompleted (still waiting), completed with a value, or completed with an error. Network libraries, file APIs, databases and timers all return Futures, so you will meet them everywhere in Flutter, for example when loading data for a screen.

Notice the order of output in the example above: the last print line runs first, because then only registers what to do later. Beginners often expect the balance to print first; understanding this order is the key to async code.

async and await

Chaining then calls gets hard to read. async and await let you write asynchronous code that reads top to bottom. A function marked async returns a Future automatically. Inside it, await pauses that function until a Future completes; the event loop keeps running other events in the meantime.

Future<int> fetchBalance() async {
  await Future.delayed(const Duration(seconds: 1));
  return 2500;
}

Future<void> main() async {
  print('Loading...');
  final balance = await fetchBalance();
  print('Balance: Rs $balance');
}

Error handling

Future<String> fetchProfile() async {
  await Future.delayed(const Duration(milliseconds: 300));
  throw Exception('No internet');
}

Future<void> main() async {
  try {
    final p = await fetchProfile();
    print(p);
  } catch (e) {
    print('Could not load: $e');
  } finally {
    print('Hide spinner');           // always runs
  }
}

Running Futures together

Future<String> loadUser() => Future.delayed(const Duration(seconds: 1), () => 'Asha');
Future<int> loadOrders() => Future.delayed(const Duration(seconds: 1), () => 7);

Future<void> main() async {
  final sw = Stopwatch()..start();
  final (user, orders) = await (loadUser(), loadOrders()).wait;   // Dart 3 record wait
  print('$user has $orders orders in ${sw.elapsedMilliseconds} ms');   // about 1000 ms, not 2000
  final all = await Future.wait([loadUser(), loadUser()]);          // list version
  print(all);
}

Common mistakes

• Forgetting await: you get a Future (printed as Instance of 'Future<int>') instead of the value, and the code continues too early. The analyser can warn about unawaited futures.
• Awaiting independent calls one by one, doubling the waiting time. Use Future.wait or record .wait.
• Marking a function async but returning void instead of Future<void>, so callers cannot await it or catch its errors.
• Thinking async runs code on another thread. It does not: it only lets the single thread do other work while waiting.