Skip to content
Tutorials Center
My learning

Topics

Lesson 138 of 146 ยท Projects

Project: An Async Pipeline

Build a concurrent processing pipeline in Swift 6 - AsyncStream sources, task groups with bounded concurrency, per-job timeouts, cancellation, an actor for aggregation, and deterministic output.

Many real programs are pipelines. Data enters at one end, passes through a series of stages, and a summary comes out at the other end: a crawler that downloads pages, parses them and indexes the words; an importer that reads rows, validates them and writes them to a database; an image service that resizes, compresses and uploads. Doing the stages one item at a time is slow. Doing everything at once can overwhelm a server, a disk or your memory. A good pipeline sits in between: it works on several items concurrently, but never on more than a fixed number.

In this project you build such a pipeline with Swift concurrency. You will combine task groups, AsyncStream, actors and cancellation into one design, and every run prints the same output, because the results are sorted and no timings are printed. The code compiles in Swift 6 language mode with strict concurrency checking, so the data-race rules from the Sendable lesson apply throughout.

The design

The pipeline has four parts:

TEXT
 source            workers (at most N at a time)         aggregator
 AsyncStream<Job> --> analyze(job) with a timeout --> AsyncStream<JobResult> --> Summary
  • The source produces Job values over time.
  • The workers run analyze on jobs concurrently, with a limit.
  • The results stream carries finished results to the next stage, so stages are decoupled.
  • The aggregator folds results into a summary.

The work itself is simulated. Each job analyzes a piece of text (counts words, finds the longest word) after a short sleep that stands in for network or disk time. That keeps the example runnable while behaving like real asynchronous work: while one job sleeps, others run.

Step 1: the building blocks, run one at a time

Start with the types and the slow, sequential version. Everything that crosses a task boundary is Sendable. For plain structs and enums with Sendable fields that is automatic.

Swift Step 1: types and a sequential run

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readLine()), it gets the next line from this box.

One job fails on purpose: the empty text throws PipelineError.emptyText. In a real pipeline a single bad input must not take down the other 9,999 items, so handling failures per job is a requirement from the start, not an afterthought. Task.sleep(for:) also throws if the task is cancelled, which is why analyze is throws even for the happy path, and why cancellation will come for free later.

Step 2: run the jobs concurrently

A task group runs child tasks in parallel and lets you collect their results as they finish. Results arrive in completion order, which is not stable, so we tag each result with its job id and sort at the end. Failures are converted into a value (JobResult.failed) inside the child task, so one failing job does not cancel its siblings, as it would in a throwing group.

Swift Step 2: a task group over all jobs

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readLine()), it gets the next line from this box.

The output has the same shape as the sequential version (job 3 fails again), but all five jobs slept at the same time, so the whole run takes about as long as the slowest job, not the sum. The two key moves are group.addTask to start work and for await result in group to collect it. Sorting restores a stable order. Whenever you present concurrent results, decide explicitly what order the reader sees.

Step 3: limit the concurrency

Starting a child task for every job is fine for five jobs and a disaster for five million. The usual cure is a sliding window: start at most limit tasks, and whenever one finishes, start the next. The pattern needs only group.next(), which waits for the next child to complete.

To prove the limit holds, the next example measures it with a small actor, Gauge, that counts how many jobs are running at once and remembers the peak. An actor is the right tool because many tasks update the counter at once, and the actor serializes those updates safely.

Swift Step 3: a sliding window of workers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readLine()), it gets the next line from this box.

Read process closely, because this pattern appears in almost every concurrent Swift program. The nested function start() takes the next job from the iterator and adds a task. The for loop primes the window with limit jobs. Then while let ... = await group.next() waits for any task to finish, records its result and immediately starts a replacement. When the iterator is empty, start() does nothing, the window drains, next() returns nil, and the loop ends.

Swift 6 allows the nested function start() to capture the group and the iterator because the closure given to withTaskGroup is not @Sendable; it runs in the caller's context. Only the closure passed to addTask has to be Sendable, and it captures just job and gauge, both safe to share.

Step 4: stream jobs from a source

Real sources do not hand you an array. They produce items over time, and you do not want to hold millions of them in memory. AsyncStream models exactly that: a producer calls yield whenever it has a value, and a consumer reads with for await. The consumer below keeps the same sliding window, now driven by the stream. Because it only asks for the next job when a slot is free, the program also gets a degree of backpressure: a slow consumer simply stops pulling.

Swift Step 4: an AsyncStream source with a bounded window

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readLine()), it gets the next line from this box.

After the stream finishes, the first loop ends, but up to limit tasks may still be running, so the second loop drains the rest. Forgetting that final drain is a classic bug: the function would return before the last results arrived.

An AsyncStream created with the closure initializer here buffers all yielded values without limit by default. A real source that can produce faster than you consume should pass a buffering policy such as .bufferingNewest(100) or produce lazily inside unfolding:. See the AsyncSequence lesson for both.

Step 5: timeouts, cancellation and stopping early

Three things go wrong in production pipelines: one job hangs, the consumer has seen enough, or the whole operation is abandoned. Structured concurrency gives clean answers to all three, because cancellation flows down from parent to children and every child checks it at await points like Task.sleep.

A timeout is a race between the real work and a sleeping task; the first to finish wins and the other is cancelled. An early stop is a break out of a for await loop over an endless producer: leaving the loop ends the stream, which triggers onTermination, which cancels the producer's task.

Swift Step 5: a timeout helper and an endless producer

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readLine()), it gets the next line from this box.

Look at what withTimeout guarantees. If operation finishes first, group.next() returns its value, and defer { group.cancelAll() } cancels the sleeping timer as the function leaves. If the timer fires first, its throw TimedOut() propagates out of group.next(), the group cancels operation, and because fetch is sleeping in a cancellable Task.sleep, it stops almost immediately instead of finishing its 2000 ms. If your real work never checks for cancellation (a tight CPU loop, a blocking call), the timeout would still return on time but the work would keep running; call try Task.checkCancellation() inside long loops.

The producer part shows the same idea from the other side. The consumer breaks after five numbers, nobody calls cancel() by hand, and yet the producer stops: the stream's termination handler does it. The final line confirms that the counter stopped growing. The loop lives in its own function on purpose: in top-level code the loop's hidden iterator is not released when the loop ends, so the stream would not terminate until the program does. Inside a function the iterator dies at the break.

Step 6: the complete pipeline

Now assemble everything. The pipeline has a source stream, a bounded set of workers where each job gets its own timeout, a second stream that carries results, and an aggregator that runs at the same time as the workers. The summary uses only order-independent operations, so the printed report is the same on every run.

Swift Step 6: source, workers, results stream and aggregator

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readLine()), it gets the next line from this box.

Trace the data flow once. runPipeline creates the results stream and starts the aggregator with async let, so it runs at the same time as the workers. runWorkers pulls from the source with a window of three, gives each job its own 100 ms timeout, and yields each finished result to the results stream. When the source ends and the window drains, results.finish() closes the stream, the aggregator's for await loop ends, and summary becomes available. Closing the results stream is what ends the downstream stage; if you forget finish(), the aggregator waits forever and the program hangs.

The summary compares the longest words with a tuple comparison, (count, word), so that when two words have the same length the alphabetically later one wins. Any rule that does not depend on arrival order would work; the point is that the final answer must not depend on which task happened to finish first.

Design notes and pitfalls

  • Pick the failure policy on purpose. withThrowingTaskGroup cancels every sibling when one child throws, which suits "all or nothing" work. A pipeline that should survive bad items converts errors to values inside the child task, as attempt does.
  • Do not share mutable state between children. The children return values and only the parent mutates results. Where children must share a counter, as Gauge does, use an actor.
  • Results come back in completion order. Sort, or key by id, before showing anything to a person or a test.
  • Cancellation is cooperative. A child stops only when it reaches an await that checks cancellation or calls Task.checkCancellation(). Long synchronous loops must check themselves.
  • Choose the limit by the bottleneck. For network calls, tens or hundreds can be right. For CPU work, the number of cores is the useful maximum, and this sandbox has only one.
  • Test with sleeps shortened, not removed. The structure of a concurrent program is easiest to verify with small, fixed delays and order-independent assertions, as here.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why does attempt catch errors and return a JobResult instead of letting them propagate out of the child task?

    A throwing task group cancels the remaining children when one throws. Converting the error into a value keeps the other jobs running.
  2. 2. What does the sliding-window loop while let r = await group.next() { ...; start() } accomplish?

    next() returns when any child finishes. Starting one replacement per completion keeps the number of running children constant until the input is exhausted.
  3. 3. What happens if the workers stage forgets to call results.finish()?

    An AsyncStream ends only when it is finished or its consumer stops. Without finish() the downstream stage keeps waiting for more values.
  4. 4. How does break in a for await loop over the endless numbers stream stop the producer task?

    When the iterator goes away the stream is terminated and its onTermination handler fires. The handler cancels the producer, whose loop checks Task.isCancelled.
  5. 5. Why are results sorted by id before printing?

    Whichever child finishes first is delivered first. Sorting (or keying by id) makes the output stable.

Summary

  • A pipeline has a source, concurrent workers, and an aggregator; decoupling stages with AsyncStream keeps each one simple.
  • Use a task group for concurrency and a sliding window (group.next() plus addTask) to bound it; drain the group after the input ends.
  • Convert per-item errors into values when one bad item must not cancel the rest; use a throwing group for all-or-nothing work.
  • Build timeouts by racing the work against Task.sleep in a throwing group and cancelling the loser.
  • Producing from an AsyncStream stops when the consumer leaves the loop if you cancel in onTermination; always finish() a stream you create.
  • Make output deterministic by sorting and by using order-independent summaries, and use an actor for shared counters such as the Gauge.

Next: Project: A JSON Parser