A worker pool
A queue and a finished counter
A pool is a queue of work that several workers pull from, and a counter of workers that have finished. Three TVars carry the state and no lock is written by hand:
- queue :: TVar [Job], where a worker takes the head inside a transaction.
- results :: TVar [Int], where a worker conses its result; the order is not the order of the jobs.
- finished :: TVar Int, incremented by a worker that finds the queue empty.
Taking a job is one transaction: read the queue, and if it is empty return Nothing; otherwise write the tail and return the job. Two workers cannot take the same job, because the read and the write commit together.
Three workers and six jobs
module Main (main) where
import Control.Concurrent (forkIO)
import Control.Concurrent.STM
import Control.Monad (replicateM_, when)
newtype Job = Job Int
deriving (Show)
worker :: TVar [Job] -> TVar [Int] -> TVar Int -> IO ()
worker queue results finished = loop
where
loop = do
next <- atomically $ do
jobs <- readTVar queue
case jobs of
[] -> pure Nothing
Job n : rest -> writeTVar queue rest >> pure (Just n)
case next of
Nothing -> atomically (modifyTVar' finished (+ 1))
Just n -> do
atomically (modifyTVar' results (n * 2 :))
loop
main :: IO ()
main = do
queue <- newTVarIO (map Job [1 .. 6])
results <- newTVarIO []
finished <- newTVarIO 0
replicateM_ 3 (forkIO (worker queue results finished))
atomically $ do
done <- readTVar finished
when (done < 3) retry
values <- readTVarIO results
print (length values, sum values)
ghc -Wall -O1 -threaded -o pool pool.hs
./pool
(6,42)
Six jobs, each doubled, and the sum of the results is 42. The number is the same on every run, even though the order of the results is not: the workers sleep nowhere and the runtime decides which one takes which job. Counting the results and summing them is what makes the output stable.
The results and their order
A pool returns results in completion order, which is a fact to design around:
- If the order matters, the job carries an index and the results are sorted by it at the end, as the earlier lesson on sorting showed.
- If the results are a set of independent values, a count and a sum are enough, and the order is irrelevant.
- A result list built with : is reversed with respect to completion order; the sort or the sum hides it, and a reverse would show what the runtime did.
The same rule holds in every language with a work queue: the queue is ordered and the completion is not. The capstone job runner adds an id to every job for exactly this reason.
A shutdown that waits
The main thread waits with one transaction: read the counter and retry while it is below three. That is the condition-variable pattern of the STM lesson applied to a counter, and it costs one blocked thread, not a polling loop.
atomically $ do
done <- readTVar finished
when (done < 3) retry
A worker that finds the queue empty increments the counter and returns, so the last of the three wakes the main thread. If a worker died with an exception, the counter would never reach three and the main thread would wait for ever: a supervised pool needs the worker body wrapped in a finally that increments the counter, which is the asynchronous exceptions lesson applied to the pool. The capstone takes the design from here: a queue, a result TVar, a counter, a logger thread and a stop flag.
This is the last lesson of Part 8. The next part is the first capstone, a CSV report processor built over seven lessons, which uses the file, parsing and formatting lessons of the first two thirds of the course.
Exercises
- Add job ids and sort the results by id before printing.
- Change the pool to eight workers and explain the counter.
- Wrap the worker body in finally so a dying worker still counts.
- Give each worker a name and log the job it took, and read the interleaving.
- Add a bounded queue and a slow worker, and watch the others wait.
- Measure the pool with one worker and with four and compare.
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
How does a worker take a job?
Answer
In one transaction that reads the queue and writes the tail
The read and the write commit together, so two workers cannot take the same job.
-
What does the finished counter count?
Answer
Workers that found the queue empty
Each worker increments it once and returns, so the main thread waits for three.
-
Why is the printed sum stable when the result order is not?
Answer
The sum is commutative and the number of results is fixed
Six results of a fixed set sum to 42 whatever the order.
-
What does this program print?
module Main (main) where import Control.Concurrent.STM import Control.Monad (replicateM_) main :: IO () main = do results <- newTVarIO [] replicateM_ 3 (atomically (modifyTVar' results (1 :))) readTVarIO results >>= print . lengthAnswer
3
Three appends of one element give a list of length three.
-
What does the main thread do while the workers run?
Answer
It blocks in a transaction that retries until the counter reaches three
The retry parks the thread and the last increment wakes it.
-
What happens if a worker dies with an exception?
Answer
The counter never reaches the target and the main thread waits for ever
The exception is in the worker thread, so a finally is needed to count it.
-
What does this program print?
module Main (main) where import Control.Concurrent.STM main :: IO () main = do box <- newTVarIO (2 :: Int) atomically (modifyTVar' box (* 3)) readTVarIO box >>= printAnswer
6
The transaction multiplies the value by three.
-
Why add a job id?
Answer
The results come back in completion order, so the id restores the job order
Ordering by id at the end is the standard way to make a pool deterministic.
-
What does this program print?
module Main (main) where main :: IO () main = print (sum [1 .. 6 :: Int])Answer
21
The sum of 1 to 6 is 21.
-
What does the capstone job runner add to this design?
Answer
A stop flag, a logger thread and a benchmark
The capstone lessons extend this pool with shutdown, logging and timings.
The code on this page was built with GHC 9.10.3 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev