Capstone C: the channel queue

A queue between a producer and a consumer needs a decision about its capacity. Unbounded, the producer can run ahead of the consumer until the memory of the process is gone. Bounded at two, the producer waits when two jobs are waiting, and the memory is two jobs. This lesson builds the queue of the capstone with Channel.CreateBounded and shows both halves of that decision.

A bounded queue

The first program is the smallest demonstration of backpressure: a channel with room for one item, two attempts to write, one read, and another write. TryWrite answers immediately and never waits, so a full channel is a false and not a block:

using System.Threading.Channels; Console.WriteLine("bounded 1.0"); var channel = Channel.CreateBounded<int>(1); Console.WriteLine($"write 1 {channel.Writer.TryWrite(1)}"); Console.WriteLine($"write 2 {channel.Writer.TryWrite(2)}"); Console.WriteLine($"read {channel.Reader.TryRead(out var first)} {first}"); Console.WriteLine($"write 2 again {channel.Writer.TryWrite(2)}");

dotnet run
echo "status: $?"

bounded 1.0
write 1 True
write 2 False
read True 1
write 2 again True
status: 0

The first write fills the channel and answers true. The second finds no room and answers false; the item is lost, because nobody waits for it. The read takes the first item out, which is the number one, and then the write of two succeeds. That last line is why a bounded channel is a queue and not a filter: a refused write is the decision of the caller, not a silent drop.

WriteAsync is the other half: it waits until there is room and returns a task, which is what the producer of the next section uses. ReadAllAsync on the reader waits for items and ends when the writer is completed and the last item has been read.

A producer and a consumer

The main program of the lesson writes six jobs through a channel of capacity two and reads them in a loop. The writer completes the channel after the sixth job, which is the producer saying that it has no more work; the reader ends at that moment, after the last item. Both halves are tasks, and the program awaits both:

using System.Threading.Channels; Console.WriteLine("queue 1.0"); var queue = Channel.CreateBounded<Job>(2); var producer = Task.Run(async () => { for (var i = 1; i <= 6; i++) { await queue.Writer.WriteAsync(new Job(i, i * 100)); Console.WriteLine($"wrote {i}"); } queue.Writer.Complete(); }); var consumer = Task.Run(async () => { var count = 0; await foreach (var job in queue.Reader.ReadAllAsync()) { count++; Console.WriteLine($"read {job.Id} units {job.Units}"); } return count; }); await producer; var read = await consumer; Console.WriteLine($"read {read} jobs, completed {queue.Reader.Completion.IsCompleted}"); record Job(int Id, int Units);

dotnet run
echo "status: $?"

queue 1.0
wrote 1
wrote 2
read 1 units 100
read 2 units 200
read 3 units 300
wrote 3
wrote 4
wrote 5
wrote 6
read 4 units 400
read 5 units 500
read 6 units 600
read 6 jobs, completed True
status: 0

The six jobs are all read, and the set of lines is the same on every run: six wrote lines, six read lines with the units of their jobs, and the last line with the count and the completion flag. The number of jobs read is the checksum, and it is what a pool of workers must also print in a later lesson.

The order of the lines

The order of the fifteen lines is not promised, and the output above is one run of it. In this run the consumer read jobs one and two before the producer printed wrote 3, which looks impossible until the order of two operations is read closely: WriteAsync returns when the item is in the channel or taken by a reader, and the Console.WriteLine after it may run after the consumer has already read the job and printed its own line.

A test over this program compares the set of lines and the last one, never the order. The next lesson keeps the channel and replaces the single reader with a pool of workers, one of which fails on purpose.

Exercises

  1. Change the capacity to one and to unbounded, run each version three times and compare the interleavings.
  2. Make the producer sleep before every write and see how the order of the lines becomes stable.
  3. Replace TryWrite with await WriteAsync in the first program and describe what the second write does now.
  4. Print the count of items left in the channel after every read with channel.Reader.Count and explain the largest value.

Questions

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

  1. What does TryWrite do when the channel is full?

    Answer

    It returns false at once and the item is not written

    The measured second write of the first program answers False.

  2. What ends the loop of ReadAllAsync?

    Answer

    The writer completes the channel and the last item is read

    queue.Writer.Complete() is the end of the input.

  3. What does this program print? using System.Threading.Channels; var channel = Channel.CreateBounded<int>(2); Console.WriteLine(channel.Writer.TryWrite(1)); Console.WriteLine(channel.Writer.TryWrite(2)); Console.WriteLine(channel.Writer.TryWrite(3));

    Answer

    True, True, False

    Two items fill a channel of capacity two.

  4. Why is the order of the fifteen lines not promised?

    Answer

    Two tasks on two threads share one console, and the scheduler decides

    The measured run has read 3 before wrote 3.

  5. What does this program print? using System.Threading.Channels; var channel = Channel.CreateUnbounded<int>(); Console.WriteLine(channel.Writer.TryWrite(1)); Console.WriteLine(channel.Writer.TryWrite(2));

    Answer

    True and True

    An unbounded channel never refuses a write.

  6. What is the last line of the main program?

    Answer

    The count of jobs read and whether the reader is complete

    The measured last line reads read 6 jobs, completed True.

  7. What does this program print? using System.Threading.Channels; var channel = Channel.CreateBounded<string>(1); channel.Writer.TryWrite("a"); Console.WriteLine(channel.Reader.TryRead(out var item) + " " + item);

    Answer

    True a

    The read succeeds and writes the item to the out parameter.

  8. What does a capacity of two protect?

    Answer

    The memory of the process, which holds two jobs and not the whole input

    A bounded channel is backpressure, and backpressure is bounded memory.

  9. What does this program print? var total = 0; for (var i = 1; i <= 6; i++) { total += i * 100; } Console.WriteLine(total);

    Answer

    2100

    The six jobs carry 100, 200, 300, 400, 500 and 600 units.

  10. What does the producer await before it completes the channel?

    Answer

    The write of the last job, which may wait for room

    Complete must come after the last write, or that job never arrives.

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