How to Exit the Asyncio Event Loop
You can exit the asyncio event loop by returning from the main coroutine used as the entry point for the asyncio program.
In this tutorial, you will discover how to exit the asyncio event loop in Python.
Need to Exit the Event Loop
Asyncio programs are executed by an event loop.
The event loop is responsible for running tasks, executing callbacks and managing non-blocking I/O.
The event loop is the core of every asyncio application. Event loops run asynchronous tasks and callbacks, perform network IO operations, and run subprocesses.
— Asyncio Event Loop
You can learn more about the asyncio event loop in the tutorial:
We execute asyncio programs using the high-level API via the asyncio.run() function.
This function takes a coroutine as an argument which is used as the entry point to the asyncio program.
You can learn more about how to run asyncio programs in the tutorial:
Running the event loop is blocking, this means it will block the calling thread until the event loop is terminated.
This raises the question, how do we exit the asyncio event loop?
We may need to exit the asyncio event loop from within the asyncio program for many reasons, such as:
How can an asyncio program exit the event loop?
It also raises related questions, such as:
- Does a running task prevent the asyncio event loop from exiting normally?
- Does a running subprocess prevent the asyncio event loop from exiting normally?
We can explore these questions with worked examples.
Run your loops using all CPUs, download my FREE book to learn how.
How to Exit the Asyncio Event Loop
An asyncio event loop can be exited by returning from the main coroutine.
We may refer to the coroutine that is passed to asyncio.run() to run the asyncio event loop as the main coroutine, for lack of a better name.
When this coroutine exits, the event loop will terminate.
This is the normal way for an asyncio program to end.
There are three ways this may occur, they are:
- The main coroutine completes, e.g. reaches the end and returns,
- The main coroutine returns early, e.g. the return expression.
- The main coroutine raises an unhandled exception, e.g. directly or indirectly.
The asyncio event loop does provide methods for stopping the event loop. These are the close() method and the stop() method.
The close() method can only be called once all tasks have stopped running otherwise a RuntimeError will be raised. It cannot be called safely from a running coroutine directly. The stop() method will schedule an attempt to close the event loop if run_forever() was called, but it too requires that all tasks have been completed otherwise it will raise a RuntimeError.
These are in a low-level API and are generally not intended for application developers, instead, they are reserved for framework developers. You may be able to trigger a close using these methods, e.g. via another thread, but they are not recommended.
Generally, these methods are intended to be called from outside the event loop, e.g. by a managing thread or process.
Now that we know how to exit the asyncio event loop, let’s look at some worked examples.
Confused by the asyncio module API?
Download my FREE PDF cheat sheet
Example of Exiting the Event Loop
The recommended way to exit the asyncio event loop is to exit the main coroutine.
In this section, we will explore the different common ways of exiting the main coroutine.
Exit the Event Loop After the Main Coroutine Finishes
We can explore the normal case of closing the asyncio event loop by letting the main coroutine run to completion.
In this example, the main coroutine will schedule a task coroutine and wait for it to complete. The task will report a message, sleep for two seconds, then report a final message. Once the task is complete, the main coroutine will resume and report a final message for exiting.
The complete example is listed below.