Capstone C: a clean shutdown

A pipeline of channels is finished when every stage says so, and the order of the goodbyes is the whole of a clean shutdown. The producer completes its channel after the last item, the workers end when their channel ends, the result channel is completed by the task that awaited the workers, and the program waits for the reading loop before it prints. This lesson shows the order, the two ways a channel can refuse to end, and a cancelled run.

The order of the stages

The program of this lesson is the pool of lesson 129 with the squares of five numbers instead of the job sums, so the checksum is small enough to check by hand: one plus four plus nine plus sixteen plus twenty-five is fifty-five. Each stage prints the line that it is done, and the flags of the two channels are printed at the end:

using System.Threading.Channels; Console.WriteLine("shutdown 1.0"); var queue = Channel.CreateBounded<int>(2); var results = Channel.CreateUnbounded<int>(); var producer = Task.Run(async () => { for (var i = 1; i <= 5; i++) { await queue.Writer.WriteAsync(i); } Console.WriteLine("producer done"); queue.Writer.Complete(); }); var workers = Enumerable.Range(1, 2).Select(worker => Task.Run(async () => { await foreach (var item in queue.Reader.ReadAllAsync()) { await Task.Delay(5); await results.Writer.WriteAsync(item * item); } Console.WriteLine($"worker {worker} done"); })).ToArray(); var finish = Task.Run(async () => { await Task.WhenAll(workers); results.Writer.Complete(); }); await producer; await finish; var values = new List<int>(); await foreach (var value in results.Reader.ReadAllAsync()) { values.Add(value); } Console.WriteLine($"results {values.Count} sum {values.Sum()}"); Console.WriteLine($"queue completed {queue.Reader.Completion.IsCompleted}, results completed {results.Reader.Completion.IsCompleted}");

dotnet run
echo "status: $?"

shutdown 1.0
producer done
worker 2 done
worker 1 done
results 5 sum 55
queue completed True, results completed True
status: 0

The producer done line is guaranteed to come before the two worker done lines, because a worker cannot end before its channel is completed and only the producer completes it. The order of the two worker lines is not promised: they are two tasks on the pool, and either can end first.

The last line is the one a shutdown is judged by. Both channels report completed, and the program printed it after the reading loop, so every value that was produced was also read. A program that printed it earlier would print the same words about a pipeline that still had work in flight.

A channel that is never completed

The failure this lesson guards against is a channel nobody completes: the reading loop waits for an item that will never arrive, and the program hangs with no output and no error. The second program shows the two facts behind that hang: a reader can wait with a timeout, and the completion of a bounded or unbounded channel is not a flag the writer sets for the reader alone.

using System.Threading.Channels; Console.WriteLine("hang 1.0"); var channel = Channel.CreateUnbounded<int>(); await channel.Writer.WriteAsync(1); try { await channel.Reader.Completion.WaitAsync(TimeSpan.FromMilliseconds(200)); Console.WriteLine("completed"); } catch (TimeoutException) { Console.WriteLine("still open"); } channel.Writer.Complete(); Console.WriteLine($"completed now {channel.Reader.Completion.IsCompleted}"); Console.WriteLine($"read {await channel.Reader.ReadAsync()}"); Console.WriteLine($"completed after the drain {channel.Reader.Completion.IsCompleted}");

dotnet run
echo "status: $?"

hang 1.0
still open
completed now False
read 1
completed after the drain True
status: 0

The wait of two hundred milliseconds ends with TimeoutException and the program prints still open. Then the writer completes the channel, and the completion is still false, because one item is still buffered: the reader has not taken it yet. Only after the read does the completion become true. A consumer that is written as await foreach (var item in channel.Reader.ReadAllAsync()) never sees that state, because the loop drains the buffer before it asks.

The drain

That behaviour is the reason a shutdown is written as three steps and not one: complete the input, await the stages, then print. The middle step is what drains the buffers, and the difference between a completed writer and a completed reader is the difference between "no more items will be written" and "every item has been read".

A cancelled run

A shutdown that only waits is not enough for a job that takes too long: the program must also be able to stop work that is still running. The third program runs a loop of a hundred steps, gives it thirty milliseconds and cancels the token:

Console.WriteLine("cancel 1.0"); using var cts = new CancellationTokenSource(); var token = cts.Token; var work = Task.Run(async () => { var done = 0; for (var i = 0; i < 100; i++) { token.ThrowIfCancellationRequested(); await Task.Delay(5, token); done++; } return done; }); cts.CancelAfter(TimeSpan.FromMilliseconds(30)); try { Console.WriteLine($"finished {await work}"); } catch (OperationCanceledException) { Console.WriteLine("stopped by the token"); } Console.WriteLine($"cancelled {token.IsCancellationRequested}");

dotnet run
echo "status: $?"

cancel 1.0
stopped by the token
cancelled True
status: 0

The token is asked twice and answers twice: once by ThrowIfCancellationRequested at the top of the loop and once by the Task.Delay of the step in progress, both of which throw OperationCanceledException. The exception is the normal way for a cancelled task to end, and the catch that prints the line is the only place that knows it was a cancellation and not a defect. Lesson 081 measured the same shape with a timeout, and lesson 080 showed the exception a task carries when nobody catches it.

The next lesson adds the one stage this pipeline still lacks: a logger that takes lines from a channel and writes them, so no two workers write to the console at once.

Exercises

  1. Print the counts of the two channels after the drain and check them against the five values.
  2. Remove the completion of the result channel and watch the program hang, then stop it with Control-C.
  3. Cancel the token after ten milliseconds instead of thirty and see whether the work finishes first.
  4. Pass the token into the workers of the first program and stop the pool after the third value.

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What must happen before a worker can end?

    Answer

    The producer completes the job channel and the worker has read the last job

    ReadAllAsync ends at the completion of its channel.

  2. What does Writer.Complete() promise?

    Answer

    That no more items will be written, not that the channel is empty

    The measured completion is still false while one item is buffered.

  3. What does this program print? using System.Threading.Channels; var channel = Channel.CreateUnbounded<int>(); await channel.Writer.WriteAsync(7); channel.Writer.Complete(); Console.WriteLine(channel.Reader.Completion.IsCompleted);

    Answer

    False

    The item is still buffered, so the reader is not complete.

  4. When does Reader.Completion end?

    Answer

    When the channel is completed and every item has been read

    That is why the drain of the second program turns False into True.

  5. What does this program print? var source = new System.Threading.CancellationTokenSource(); source.CancelAfter(TimeSpan.FromMilliseconds(20)); try { await Task.Delay(1000, source.Token); Console.WriteLine("slept"); } catch (OperationCanceledException) { Console.WriteLine("cancelled"); }

    Answer

    cancelled

    The delay is cancelled long before it ends.

  6. Which exception does Task.Delay throw when its token is cancelled?

    Answer

    OperationCanceledException, of which TaskCanceledException is a subclass

    The measured catch prints its own line for the cancellation.

  7. What does this program print? var values = new[] { 1, 4, 9, 16, 25 }; Console.WriteLine(values.Sum());

    Answer

    55

    That is the checksum of the five squares in the measured run.

  8. Why is the result channel completed by a task and not by a worker?

    Answer

    Only the task that awaits every worker knows when the last write is done

    Completing early would lose the results of the other worker.

  9. What does this program print? using System.Threading.Channels; var channel = Channel.CreateUnbounded<int>(); channel.Writer.Complete(); Console.WriteLine(channel.Reader.Completion.IsCompleted);

    Answer

    True

    With no buffered items the completed channel is complete at once.

  10. What is the three-step shutdown of a pipeline?

    Answer

    Complete the input, await the stages, then print

    The await is the drain, and the print must come after it.

The code on this page was built with the .NET SDK 10.0.303 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev

Banner image