Using Python asyncio.Event for Coroutine Signaling
Learn how to use asyncio.Event to coordinate coroutines, handle timeouts and cancellation, and avoid common pitfalls in Python async programs.

When one coroutine needs to notify others that a condition has occurred, asyncio.Event provides a clean, built-in primitive. It lets you signal across tasks without manual condition variables or polling loops. This article explains how to use it correctly, what happens when you wait or set, and where it breaks down in production code.
What asyncio.Event Does and When to Use It
asyncio.Event is a synchronization primitive that allows one or more coroutines to wait until another coroutine sets the event. It is analogous to threading.Event but designed for the asyncio event loop. Internally, it maintains a boolean flag and a set of waiters. When the flag is set, coroutines already blocked in wait() are woken; later calls to wait() observe the event as set and return immediately. When cleared, new wait() calls block until the next set.
Use an event when you need to broadcast a single signal to multiple consumers, such as a shutdown notification, a resource readiness flag, or a state change that should unblock several tasks. It is not a queue; it carries no data beyond the boolean state. For passing actual messages, prefer asyncio.Queue.
Creating and Using an asyncio.Event
Creating an event is straightforward:
import asyncio
async def main():
event = asyncio.Event()
print(event.is_set()) # False
asyncio.run(main())The event starts unset. To set it, call .set(). To clear it, call .clear(). To wait until it is set, call .wait().
import asyncio
async def worker(event):
print('worker waiting')
await event.wait()
print('worker proceeding')
async def main():
event = asyncio.Event()
task = asyncio.create_task(worker(event))
await asyncio.sleep(0.1)
event.set()
await task
asyncio.run(main())When .set() is called, tasks currently blocked in await event.wait() are scheduled to resume. A task that calls wait() after the event is set returns immediately without yielding control.
The .clear() method resets the flag to False. This is useful when you want to reuse the event for a later cycle. Clearing does not cancel wake-ups already delivered to waiters; it only affects new wait() calls after the clear. If you want a one-shot signal that later waiters should observe, leave the event set or create a new event.
Waiting with Timeouts and Cancellation
asyncio.Event.wait() does not take a timeout argument. To limit how long a coroutine waits for an event, wrap the wait in asyncio.wait_for:
import asyncio
async def main():
event = asyncio.Event()
try:
await asyncio.wait_for(event.wait(), timeout=1.0)
except asyncio.TimeoutError:
print('event not set within 1 second')
asyncio.run(main())asyncio.wait_for also works with other awaitables. If the event is not set within the timeout, it cancels the inner wait and raises asyncio.TimeoutError. If the task that called wait() is cancelled, the waiter is removed from the event's internal waiter set, so it does not leak in long-running applications.
Common Signaling Patterns
A typical pattern is a graceful shutdown signal. Multiple worker tasks wait on an event, and a main task sets it when it is time to stop.
import asyncio
async def worker(name, shutdown_event):
while not shutdown_event.is_set():
print(f'{name} working')
try:
await asyncio.wait_for(shutdown_event.wait(), timeout=1.0)
except asyncio.TimeoutError:
continue
print(f'{name} shutting down')
async def main():
shutdown = asyncio.Event()
workers = [asyncio.create_task(worker(f'w{i}', shutdown)) for i in range(3)]
await asyncio.sleep(2)
shutdown.set()
await asyncio.gather(*workers)
asyncio.run(main())Another pattern is using an event to signal that a resource is ready. For example, a connection pool initializer sets an event after the pool is populated, and request handlers wait on it before using the pool.
You can also combine events with asyncio.gather to wait for multiple signals. However, events do not carry information about which signal fired. If you need to distinguish between multiple sources, use separate events and asyncio.wait with return_when='FIRST_COMPLETED'.
asyncio.Event vs threading.Event
Both primitives share the same API: set(), clear(), wait(), and is_set(). The critical difference is that asyncio.Event.wait() is a coroutine and must be awaited, while threading.Event.wait() is a blocking method. Using threading.Event inside an async function blocks the event loop and defeats the purpose of concurrency.
| Aspect | asyncio.Event | threading.Event |
|---|---|---|
| Wait method | await event.wait() | event.wait() |
| Blocking | Non-blocking, yields control | Blocks the calling thread |
| Thread safety | Not thread-safe | Thread-safe |
| Use case | Within asyncio tasks | Across OS threads |
asyncio.Event is not thread-safe. If you need to set an event from a different thread, use loop.call_soon_threadsafe(event.set) to marshal the call onto the event loop. This is a common source of bugs in mixed-thread applications.
Pitfalls and Edge Cases
A common mistake is to treat clear() as an undo for set(). Because set() resolves the futures of waiters, those wake-ups are not retracted by clear(). Instead, clear() only makes new wait() calls block again. If you need a one-shot signal that later waiters should observe, do not clear it; create a new event instead.
Another pitfall is relying on is_set() for state checks in a race. The flag can change between the check and the next await. Use await event.wait() rather than if event.is_set(): when you need to block until the signal occurs.
Keep events for simple boolean coordination. An event does not carry data or identify which coroutine set it; if you need to pass messages or distinguish between multiple signal sources, use an asyncio.Queue or separate event instances.
Try matching browser tools
All toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.