Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 40 ยท Event Loop and Coroutines

Futures and Callbacks in asyncio

Learn how asyncio.Future works: create_future, set_result, set_exception, done callbacks, awaiting futures, and bridging callback-style code to async/await.

A Future is a promise that a value will exist later. It starts out empty ("pending"). Later, some code fills it with a result or an exception, and everything waiting for it wakes up. In day-to-day asyncio code you mostly use tasks, which are futures that run a coroutine for you. But futures are the primitive underneath, and they are the right tool for one important job: turning callback-style code into await-able code.

Creating and completing a future

Use loop.create_future() (not asyncio.Future() directly) so the future is bound to the running loop. A future is in one of three states: pending, finished with a result, or finished with an exception (or cancelled).

Python A future filled later

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 input()), it gets the next line from this box.

The coroutine awaits an empty future and is suspended. After 0.1 seconds the callback fills it, and the loop resumes the coroutine with the value. This is exactly what asyncio.sleep does internally.

Futures offer these methods:

Method Meaning
set_result(value) complete successfully
set_exception(exc) complete with an error
result() get the value; raises the exception if there is one; raises InvalidStateError if still pending
exception() get the exception, or None
done() / cancelled() state checks
cancel() cancel the future
add_done_callback(fn) run fn(future) when finished

A future can be completed only once; a second set_result raises InvalidStateError.

Exceptions and done callbacks

add_done_callback registers a plain function that receives the future when it finishes. The callback is scheduled with call_soon, so it runs on the next loop turn:

Python Done callbacks and exceptions

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 input()), it gets the next line from this box.

Awaiting a future that holds an exception raises it, so the usual try/except works. If nobody ever retrieves a failed future's exception, asyncio logs "Future exception was never retrieved" when it is garbage collected. Always await or inspect futures you create.

Bridging callback APIs to await

Older libraries report results through callbacks: "call this function when you are done". A future turns that into something you can await. Here is a fake callback-style API and an async wrapper around it:

Python Wrapping a callback API

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 input()), it gets the next line from this box.

fetch returns the future, so callers write await fetch(url) and never see callbacks. This wrapper pattern is how many async libraries are built over older callback APIs. If the callbacks run on another thread, use loop.call_soon_threadsafe(future.set_result, value) instead, because futures are not thread-safe.

Tasks are futures

asyncio.Task subclasses Future. Every future method works on a task, and task.result() is the coroutine's return value. The difference is who completes it: for a plain future, your code calls set_result; for a task, the loop does it when the coroutine ends.

Python A task behaves like a future

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 input()), it gets the next line from this box.

Which should you use?

Prefer plain async def functions and tasks in application code. Reach for a raw future only to:

  • wrap a callback-based or thread-based API (as above);
  • build a synchronization primitive of your own;
  • hand a result from one task to another, where a queue or event is not a good fit.

Also avoid add_done_callback for new logic: callbacks cannot await, and errors inside them only get logged. Inside a coroutine, await the task or future directly.

concurrent.futures.Future is different

The standard library has a second class with the same name, concurrent.futures.Future, used by thread and process pools. It is not awaitable and blocks in .result(). asyncio.wrap_future and loop.run_in_executor convert between the two worlds. Never mix them up: await works on asyncio.Future, .result() blocking works on concurrent.futures.Future.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which method creates a future bound to the running loop?

    loop.create_future() is the recommended way, because it lets the loop choose the right Future implementation.
  2. 2. What happens when you call set_result on a future twice?

    A future can be completed only once.
  3. 3. You await a future that had set_exception(ValueError('x')) called on it. What happens?

    Awaiting a failed future raises its exception, so try/except works as usual.
  4. 4. Why wrap a callback API in a future?

    The callback completes the future, and callers simply await it.

Summary

  • A Future is an empty result box; set_result or set_exception completes it exactly once.
  • Awaiting a future suspends the coroutine until it completes, and re-raises stored exceptions.
  • add_done_callback runs plain functions on completion, but await is usually better.
  • Futures wrap callback-style APIs; use call_soon_threadsafe when callbacks come from other threads.
  • Task is a Future subclass that the loop completes for you.

Next: Async iterators and generators