Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 40 ยท Timeouts and Cancellation

Cancelling Tasks and Handling CancelledError

Learn how asyncio cancellation works: task.cancel(), CancelledError, cleanup in finally, why you must re-raise, cancel messages, gather and TaskGroup cancellation.

Cancellation is how asyncio stops work that is no longer wanted: a user closed the page, a timeout expired, a sibling task failed, the program is shutting down. It is also the part of asyncio where most subtle bugs live, because cancellation is not a hard kill. It is a polite request delivered as an exception at the next await, and your code decides what happens next.

This lesson explains the exact mechanism, shows what the cancelled task and its awaiters observe, and gives you the rules that keep cancellation reliable.

How cancellation works

Calling task.cancel() does not stop the task immediately. It schedules a CancelledError to be thrown into the coroutine at the point where it is currently suspended (the await it is waiting on). From there it behaves like any exception: it unwinds the stack, runs finally blocks and context-manager exits, and, if nothing stops it, ends the task in the cancelled state.

Python The life of a cancelled task

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.

Study the order of the output: the request is made, then the worker runs its except and finally, and only then does the await task in main raise. A cancelled task is done() and cancelled(); calling result() on it raises CancelledError.

CancelledError is special

CancelledError inherits from BaseException, not from Exception. That is deliberate: a normal except Exception: handler does not swallow it, so ordinary error handling cannot accidentally prevent cancellation. But a bare except: or except BaseException: does catch it, which is almost always a bug.

Three rules follow:

  1. Re-raise it if you catch it. Catch it only to do cleanup or logging, then raise.
  2. Use finally for cleanup that must always run; it executes for success, errors and cancellation alike.
  3. Never await forever in cleanup. The cancelled task still has to finish promptly, or whoever cancelled it will wait.

What happens if you swallow it

Here is a task that catches CancelledError and carries on. The cancel requests are counted (cancelling()), but the task is not cancelled, because it never let the exception escape.

Python Swallowing cancellation (an anti-pattern)

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.

task.cancel() returns True if the request was made, and False if the task was already done. task.cancelling() counts how many requests are outstanding, and task.uncancel() decrements it; you will meet uncancel() in the next lesson, because asyncio.timeout() and TaskGroup use it internally.

Cancelling groups of tasks

  • gather(): cancelling the future returned by asyncio.gather(...) cancels every child. If one child raises, the others keep running unless you handle it, which is one reason TaskGroup is recommended for new code.
  • TaskGroup: when any child raises, the group cancels all the other children and then raises an ExceptionGroup that you catch with except*.
  • Cancelling the parent cancels whatever the parent is awaiting at that moment, so cancellation flows down through await chains automatically. This is structured behaviour you get for free when you await coroutines directly.
Python Cancelling gather and TaskGroup

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.

Cancel, then wait

Calling cancel() only requests cancellation. If you need to be sure the task has finished its cleanup (closed its files, released its locks), await it afterwards:

Python
task.cancel()
try:
    await task
except asyncio.CancelledError:
    pass            # expected: we cancelled it ourselves

A small helper keeps this tidy:

Python
async def cancel_and_wait(task: asyncio.Task) -> None:
    task.cancel()
    await asyncio.gather(task, return_exceptions=True)

Be careful with the except asyncio.CancelledError: pass pattern: if the code around await task is itself cancelled, you would hide that too. When in doubt, check task.cancelled() or use gather(..., return_exceptions=True) as above.

Cancellation points

A task can only be cancelled where it is suspended. A coroutine with no await in a loop cannot be cancelled until it returns. If you write long loops, add an await asyncio.sleep(0) at sensible intervals to give cancellation (and other tasks) a chance. Calls to blocking functions, time.sleep, and CPU-heavy code are all uncancellable; see running blocking code.

Cancellation in practice

  • A web server cancels the handler task when the client disconnects. Code that runs in a finally must therefore be quick and safe.
  • Background tasks you create with create_task() should be stored (a set or a TaskGroup) so you can cancel them at shutdown and so they are not garbage collected early.
  • Use task.set_name() or the name= argument; names make logs and asyncio.all_tasks() output readable, as debugging shows.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does task.cancel() do?

    Cancellation is cooperative. The exception is thrown in at the suspended await and unwinds the coroutine normally, running finally blocks.
  2. 2. Why does "except Exception:" not catch CancelledError?

    CancelledError is a BaseException subclass so that ordinary error handling does not accidentally swallow cancellation.
  3. 3. You catch CancelledError to log a message. What should you do next?

    Re-raising lets the cancellation complete. Swallowing it leaves the task running and confuses whoever requested the cancel.
  4. 4. How can you be sure a cancelled task has finished its cleanup?

    cancel() only requests. Awaiting the task waits until its finally blocks have run and it has ended.
  5. 5. Why can a "for" loop of pure calculations not be cancelled midway?

    The exception can only be thrown in where the coroutine is suspended. No await means no cancellation point.

Summary

  • task.cancel() throws CancelledError into the task at its next suspension point; it is a request, not a kill.
  • Clean up in finally, re-raise CancelledError if you catch it, and keep cleanup short.
  • CancelledError is a BaseException; swallowing it is a bug that makes tasks unstoppable.
  • Cancel, then await the task if you need its cleanup to be finished; gather and TaskGroup cancel their children.

Next: Shielding work and safe cleanup