asyncio.Barrier is a synchronization primitive for coordinating several asynchronous tasks that must reach the same checkpoint before any of them continues. It is useful in phased pipelines, concurrent tests, simulations, parallel initialization, batch processing, and any design where independent coroutines must finish one stage together.
What an asynchronous barrier does
A barrier is created with the expected number of participants. Each task calls await barrier.wait() after completing its current stage. Tasks that arrive early are suspended. When the last participant arrives, all waiting tasks are released and the barrier can be used again.
import asyncio
async def worker(name, barrier):
print(name, "preparing")
await asyncio.sleep(1)
print(name, "waiting")
await barrier.wait()
print(name, "next phase")
async def main():
barrier = asyncio.Barrier(3)
await asyncio.gather(
worker("A", barrier),
worker("B", barrier),
worker("C", barrier),
)
asyncio.run(main())No worker enters the next phase before all three have reached the barrier. Waiting does not block the event-loop thread. Other runnable coroutines can continue while a participant is suspended.
When to use asyncio.Barrier
Use a barrier when work naturally happens in rounds. A data-processing application may fetch information from several sources in parallel, normalize each result, and then require every source to be ready before comparison begins. A simulation may update all agents and then wait before computing the next state. A test may align multiple clients at the exact point where a race condition should be exercised.
Barriers are also helpful during parallel startup. A database connection, cache warm-up, and configuration loader may run concurrently, while the application should accept traffic only after all three are ready. The barrier documents that contract directly.
A reusable synchronization point
After releasing a complete group, asyncio.Barrier resets itself for another cycle. This makes it suitable for iterative algorithms:
async def participant(index, barrier):
for round_number in range(3):
await perform_stage(index, round_number)
await barrier.wait()
await combine_results(index, round_number)
await barrier.wait()The example has two synchronization points per round. The first confirms that individual work is complete. The second prevents any participant from starting the next round before consolidation has finished.
The value returned by wait
wait() returns a distinct integer to each participant, generally between zero and parties - 1. The return value can elect exactly one task to perform a single action:
position = await barrier.wait()
if position == 0:
print("One participant records the completed phase")Do not assume a specific coroutine will always receive zero. Treat the value as temporary leadership for that barrier cycle, not as a stable task identity.
Using a barrier as an async context manager
A barrier can also be used with async with when the synchronization belongs clearly to a block:
async with barrier:
await process_phase()This form can make intent easier to read, but it does not change the fundamental need for every expected participant to enter the barrier.
Cancellation, broken barriers, and recovery
A barrier depends on all participants reaching the checkpoint. If one task fails, is cancelled, or exits before calling wait(), the remaining tasks may wait forever. Production code should therefore define timeout and cancellation behavior.
try:
await asyncio.wait_for(barrier.wait(), timeout=5)
except TimeoutError:
await barrier.abort()abort() marks the barrier as broken and causes current or future waiters to receive an exception. reset() returns it to an empty state. Recovery must be coordinated so that no coroutine mistakes an interrupted round for a successful one.
Barrier versus Event, Lock, and Semaphore
asyncio.Event announces that a condition became true, but it does not count how many tasks arrived. asyncio.Lock provides mutual exclusion around shared state. asyncio.Semaphore limits concurrent access to a resource. A barrier does not protect data and does not impose a concurrency limit. Its role is to align a fixed number of participants at a meeting point.
Related tutorials include Python asyncio.Runner, Python queue.SimpleQueue, Python contextvars, and Python TopologicalSorter.
Design rules that prevent deadlocks
The participant count must exactly match the tasks that will call wait(). Creating a barrier for five tasks and starting only four produces an indefinite wait. Do not share one barrier between unrelated groups, because tasks from separate rounds may accidentally satisfy the same count.
Place synchronization close to the phase it represents. A hidden barrier inside a generic helper makes the waiting behavior difficult to understand. Use names such as startup_barrier, batch_barrier, or round_barrier.
Failures before the barrier must be propagated. One robust pattern is to run participants inside asyncio.TaskGroup, cancel the group when a task fails, and abort the barrier so that existing waiters are released with an error.
Deterministic concurrent tests
Barriers are valuable in tests because they replace unreliable timing guesses. Instead of adding several sleep() calls and hoping tasks overlap, each coroutine reports its arrival through the barrier. The test then knows exactly when the competing operations can proceed.
Always add a timeout in test code. A bug should fail the test instead of freezing the entire suite. Barrier properties can help diagnostics, but production logic should not rely on observations that can change immediately due to scheduling.
A phased processing example
import asyncio
async def process(name, barrier):
for batch in range(2):
print(name, "reading", batch)
await asyncio.sleep(0.2)
leader = await barrier.wait()
if leader == 0:
print("all workers read batch", batch)
await barrier.wait()
async def main():
barrier = asyncio.Barrier(3)
async with asyncio.TaskGroup() as group:
for number in range(3):
group.create_task(process(f"worker-{number+1}", barrier))
asyncio.run(main())The first checkpoint guarantees that every worker has read the batch. One elected participant records completion. The second checkpoint prevents a fast task from moving into the next batch while the shared completion step is still taking place.
Handling dynamic workloads
A barrier works best with a fixed participant set. If workers join and leave dynamically, a queue, event, condition, or explicit coordinator may fit better. Trying to constantly recreate barriers around a changing pool often produces fragile lifecycle logic.
For optional tasks, decide membership before the round begins. Start only the selected participants and create the barrier with that exact count. If the count may be one, verify whether synchronization adds value or whether a direct call is clearer.
Performance considerations
A barrier is lightweight compared with blocking threads, but synchronization still creates coordination overhead. Do not place it inside extremely small operations merely to make tasks advance in lockstep. Let independent work proceed independently and synchronize only where correctness requires a shared boundary.
Measure the slowest participant because each round is limited by it. A consistently slow worker creates idle waiting for all others. The barrier reveals this imbalance but does not solve it. Profiling, partitioning, and workload balancing remain necessary.
Conclusion
asyncio.Barrier provides a clear way to coordinate coroutines across reusable phases. It suspends tasks without blocking the event loop, elects one participant when useful, and supports abort and reset operations. Use it when a fixed group must all reach the same point before proceeding. For authoritative details, consult the official asyncio synchronization documentation and the official task documentation.
