Grokking Concurrency in Python
Vote

0% completed

​

Conditions, Events, Semaphores and Barriers

Semaphore

Event

Condition

Barrier

Choosing the Tool

In Production

Key Takeaways

Practice Questions

Conditions, Events, Semaphores and Barriers
Conditions, Events, Semaphores and Barriers

Two of Harvest's fetch workers pause for two seconds between requests, one with time.sleep(2.0) and the other with stop.wait(2.0). When the operator asks the crawl to stop, the first worker keeps sleeping until its two seconds are over, while the second returns at once and exits.

Threads wait for more than shared data: a free slot on a website, a stop request, a new page, or the end of a stage. The threading module has four tools for those waits, and each one has a job it is wrong for.

Semaphore

A crawler that respects a website's limits sends only a few requests at a time to it. A semaphore is a counter of free slots: acquire() takes a slot, waiting if none is free, and release() gives one back. threading.Semaphore(2) lets at most two threads inside the with block at the same time:

site_limit = threading.Semaphore(2) def polite_fetch(n): with site_limit: return fetch(n)

The demos ran with Python 3.15.2 on a Linux virtual machine with 2 virtual CPUs (one physical core). The test site answers each request after 250 milliseconds and records the most requests it served at once:

Output:

$ python3.15 semaphore.py 8 threads, no limit 8 pages in 0.25 s, at most 8 requests in progress at once 8 threads, Semaphore(2) 8 pages in 1.01 s, at most 2 requests in progress at once

Eight pages took four rounds of 250 milliseconds, and that slower crawl is the intended result.

The wrong job for a semaphore is protecting data, which is a lock's job. A semaphore has no owner, so an extra release() made by mistake adds a slot without any error. threading.BoundedSemaphore raises ValueError when it is released more times than it was acquired.

Event

An event is a flag that starts unset: set() raises it, is_set() reads it, and wait(timeout) blocks until the flag is set or the timeout passes. Harvest uses one as its stop signal:

def worker_sleep(n): while not stop.is_set(): fetch(n) time.sleep(2.0) # polite pause before the next request to this site def worker_event(n): while not stop.is_set(): fetch(n) stop.wait(2.0) # the same pause, but it ends as soon as stop is set

Four workers ran for half a second before stop.set():

Output:

$ python3.15 event.py worker_sleep all 4 workers stopped 1.76 s after stop.set() worker_event all 4 workers stopped 0.00 s after stop.set()

No other thread can wake a thread from time.sleep(), so the sleeping workers noticed the stop only when their pauses ended. stop.wait(2.0) pauses exactly like time.sleep(2.0) when nothing happens, and every waiting thread returns at once when the event is set.

The wrong job for an event is counting or passing data. An event has only two states and stays set until someone calls clear(). A short signal made with set() and then clear() is missed by any thread that was not yet waiting.

Condition

Two indexer threads wait for pages to appear in a shared list. A condition variable is a lock combined with a waiting list: a thread holding the lock calls wait(), which releases the lock and sleeps until another thread calls notify() or notify_all(). The thread takes the lock back before wait() returns. Here are two ways to take a page:

def take_with_if(): with cond: if not frontier: cond.wait() return frontier.pop() def take_with_while(): with cond: while not frontier and not done: cond.wait() return frontier.pop() if frontier else None

The demo starts both indexers, adds one page, and calls notify_all(). Later it sets done and notifies again:

Output:

$ python3.15 condition.py if; python3.15 condition.py while --- if indexer-1 got page 7 indexer-2 died: IndexError: pop from empty list --- while indexer-1 got page 7 indexer-2 got None

notify_all() woke both indexers for one page. The first took the lock and the page. The second took the lock next, and with if, it called pop() on an empty list, because wait() returns without testing anything. A thread woken from wait() must check its condition again, because another thread may have changed the data first. The while version does this, and cond.wait_for(predicate) runs the same loop for you.

notify() wakes only one waiting thread, but the while check is still needed, because a thread that was not waiting can take the page first.

One page, two woken indexers
One page, two woken indexers

The wrong job for a condition is a simple hand-off of items between threads. The standard library class queue.Queue already combines a list, a lock, and conditions, and code that uses it cannot forget the while.

Barrier

Harvest can crawl one depth at a time with four workers, where no worker starts the next depth until the current one is fetched. A barrier is a meeting point for a fixed number of threads: each thread that calls wait() blocks until that number of threads have called it, and then all of them continue. The optional action runs once after all have arrived and before any continues, and Harvest uses it to compute the next depth:

barrier = threading.Barrier(WORKERS, action=next_level, timeout=2.0) def worker(i): while level: for n in level[i::WORKERS]: found.extend(links(fetch(n))) barrier.wait()

Page 5 on the test site returns an HTTP 404 error:

Output:

$ python3.15 barrier.py depth 1 done, next depth has 4 pages depth 2 done, next depth has 9 pages depth 3 done, next depth has 16 pages worker-3 died: HTTPError: HTTP Error 404: Not Found worker-0 died: BrokenBarrierError worker-1 died: BrokenBarrierError worker-2 died: BrokenBarrierError visited 30 pages, failed: []

worker-3 died at depth 4 and never reached the barrier. After the two-second timeout on wait(), the barrier broke, and every waiting thread got BrokenBarrierError. Without a timeout, they would have waited forever.

The wrong job for a barrier is any group where a member can fail or leave. The careful worker catches fetch errors inside its loop and always reaches barrier.wait():

Output:

$ python3.15 barrier.py --careful depth 1 done, next depth has 4 pages depth 2 done, next depth has 9 pages depth 3 done, next depth has 16 pages depth 4 done, next depth has 6 pages depth 5 done, next depth has 2 pages depth 6 done, next depth has 0 pages visited 38 pages, failed: [(5, 'HTTP Error 404: Not Found')]

A worker that cannot continue at all should call barrier.abort(), which breaks the barrier at once.

Choosing the Tool

The thread waits forToolWrong for
A free slot, with at most N threads insideSemaphore or BoundedSemaphoreProtecting data, which needs a Lock
A one-time signal to many threads, such as stopEventCounting, or a signal that must be set and cleared again
Shared data to reach some stateCondition, with a while loop or wait_forPlain hand-off of items, which queue.Queue already does
All N threads to finish a stageBarrier, with a timeoutGroups where a thread can fail and never arrive

In Production

What you seeWhat it meansHow to check
A remote site rate-limits or blocks the crawlerToo many requests in progress at onceCount requests per site; put a Semaphore around each site's requests
Shutdown takes as long as the longest pause in any workerWorkers pause with time.sleepReplace long time.sleep calls with stop.wait(...)
A consumer sometimes fails on empty dataA Condition.wait() inside if instead of whileCheck that a loop re-tests the condition around every wait()
Workers hang, then all fail with BrokenBarrierErrorOne party died before the barrierFind the first exception in the logs; catch errors inside the stage

Key Takeaways

  • A Semaphore(2) kept the test site at two requests in progress; BoundedSemaphore makes an extra release an error.
  • stop.wait(2.0) ends when the event is set, which cut shutdown from 1.76 seconds to 0.00.
  • A thread woken from Condition.wait() must check its condition again in a while loop.
  • A Barrier makes threads finish a stage together, and its action runs once per stage.
  • A barrier waits for a party that died, so give it a timeout and make every party arrive or call abort().

The next lesson, Producer and Consumer With a Queue, builds Harvest's fetch and index stages around queue.Queue, the class that already guards a shared list safely.

Practice Questions

Try each question first, then open the answer.

1. Harvest's workers check a stop flag at the top of a loop that ends with time.sleep(30). Shutdown takes up to 30 seconds. What fixes this?

<details> <summary>Show answer</summary>

Make the stop flag a threading.Event and replace time.sleep(30) with stop.wait(30). The pause is the same when nothing happens, but every waiting thread returns at once when the event is set.

</details>

2. Two consumers wait with if not items: cond.wait(), and a producer calls notify_all() after adding one item. What can go wrong?

<details> <summary>Show answer</summary>

Both wake, the first takes the item, and the second finds the list empty. In the demo it failed with IndexError: pop from empty list. Use while not items: cond.wait() or cond.wait_for(...).

</details>

3. Four workers meet at a Barrier(4) with no timeout, and one raises an exception during a stage. What happens to the other three?

<details> <summary>Show answer</summary>

They wait forever, because the fourth party never arrives. A timeout turns the hang into BrokenBarrierError; catching errors inside each stage prevents it.

</details>

4. Harvest must send at most three requests at a time to each website. Which tool do you use, and how many?

<details> <summary>Show answer</summary>

One BoundedSemaphore(3) per website, kept in a dictionary keyed by site name. A single semaphore would limit the crawler to three requests in total, not three per site.

</details>

Reading Progress

0%


Vote for new content

On This Page

Semaphore

Event

Condition

Barrier

Choosing the Tool

In Production

Key Takeaways

Practice Questions