The Viewer Handler as a Coroutine

You can now write a coroutine, await another and run the outermost one. This lesson rewrites the capstone’s viewer handler in that style, and only the viewer handler: the board, broadcast and the scorekeeper stay where Chapter 10 left them. Here is the Chapter 10 loop, then the coroutine you will write:

Chapter 10, a thread per viewer:
  snapshot = wait_and_take(outbox, CHECK_EVERY)
  nothing yet: notice_close(connection)
  connection.send(text)
  last version sent: connection.close(1000, ...)
  except ConnectionClosed: leave quietly

Chapter 11, a coroutine:
  snapshot = await next_snapshot()
  (next_snapshot waits until there is one)
  await connection.send(text)
  None: await connection.close(1000, ...)
  except ConnectionClosed: leave quietly

Much stays the same. The join snapshot comes first. One sender per viewer, the handler itself, sends only the newest snapshot. A connection that ends raises ConnectionClosed, which ends the handler quietly. And the quiz ends the same way: the last snapshot, then a close with 1000. What changes is every place the handler waits.

Why not Event.wait()

In Chapter 8, wait_and_take waited with the outbox’s Event.wait(timeout=...). That call blocks: the thread that makes it does nothing else until the event is set or the timeout passes. With a thread per viewer, that was the point. On an event loop it is a disaster, because the thread it blocks is the loop’s only thread, and every other viewer was waiting for that thread to run them.

pl_ws.py, a program written for this course that plays every client, shows the difference with two handlers of its own. Beside each, a ticker coroutine counts every 0.05 s. In a run, the ticker ran 9 times while one handler waited with await asyncio.sleep(0.5), and 0 times while the other waited with time.sleep(0.5). Both waited half a second. Only the first one handed control back while it waited.

next_snapshot()

So the handler is given a coroutine function to await instead, next_snapshot, and this chapter supplies it. Awaiting next_snapshot() gives the join snapshot first, then the newest snapshot each time there is a newer one, and None once the quiz is over. While nothing new has arrived, it waits without blocking: the handler pauses at that await, and the loop serves other viewers. It is built on asyncio tools this taste does not teach, an asyncio.Event among them, which can be awaited instead of waited on.

Read it as Chapter 8’s outbox and Chapter 10’s ending, seen from inside the handler. Newest only is the outbox’s rule. None is the last-version rule: the viewer has been given the last snapshot, so close with 1000.

One thing is left out. The Chapter 10 handler looked at the connection while idle, to notice a viewer that had gone. Here a viewer who leaves is noticed at the next send, which raises ConnectionClosed. Watching the connection while also waiting for a snapshot takes two things happening at once inside one handler, which needs tasks, and tasks belong to Lesson 4’s list.

Three awaits

In websockets.asyncio, send, recv and close on a connection are coroutine functions, so each is awaited: await connection.send(text), await connection.close(1000, "the quiz is over"). Forget the await on a send and Lesson 2’s warning comes back: the call only made a coroutine, nothing ran it, and the viewer received nothing.

Your handler awaits exactly three things: next_snapshot(), connection.send(...) and connection.close(...). When you press Submit, the check runs your coroutine one step at a time with stand-ins, so it can see every place your handler hands control back. Because it runs your coroutine with no event loop, your handler may await only those three; awaiting anything that needs a loop, such as asyncio.sleep(0.1), is reported as a mistake.

The asyncio server, read only

This is the shape of a server built on websockets.asyncio, for recognition. You will not write it in this course:

import asyncio

from websockets.asyncio.server import serve


async def handler(connection):
    await connection.send("hello")


async def main():
    async with serve(handler, "127.0.0.1", 0) as server:
        await server.serve_forever()


asyncio.run(main())

Compare it with Chapter 6. serve takes a handler with one argument, the connection, as the sync server did, but the handler is a coroutine function. The with block becomes async with, a with whose setup and cleanup are awaited, and serve_forever is awaited instead of called. One asyncio.run at the bottom starts it all. To read every message from a client, asyncio code writes async for message in connection:, a for loop whose every step is awaited. Both forms appear only in fragments like this one in this course.

Your task

In async_scoreboard.py, write viewer_handler(connection, next_snapshot). Loop: await next_snapshot(); if it gave None, await connection.close(1000, "the quiz is over") and return; otherwise await connection.send(...) with scoreboard_messages.encode_message(snapshot). Wrap the loop in try and except ConnectionClosed, and return quietly from the except. That is about nine lines.

Press Run. The first Lesson 3 section runs your handler under asyncio.run with a stand-in connection whose send and close are coroutine functions that record what they are given, and a next_snapshot that gives three snapshots and then None. The second has pl_ws.py serve your handler with websockets.asyncio to three real viewers on 127.0.0.1, then run the ticker comparison. A finished version, run on the site, printed:

--- Lesson 3: your handler with a stand-in connection
sent version 0
sent version 1
sent version 2
closed 1000 the quiz is over
--- Lesson 3: your handler served by websockets.asyncio
pl_ws.py, a program written for this course, serves your handler with websockets.asyncio and plays three viewers:
scenario async-viewers: your async viewer_handler served by websockets.asyncio; three viewers; versions 1 to 3, then the end of the quiz
viewer A received versions [0, 1, 2, 3], then the server closed it with 1000 'the quiz is over'
viewer B received versions [0, 1, 2, 3], then the server closed it with 1000 'the quiz is over'
viewer C received versions [0, 1, 2, 3], then the server closed it with 1000 'the quiz is over'
every handler ran on the main thread: True
threads in this process while serving: 1
now this program's own code: a ticker that counts every 0.05 s, beside a handler that waits 0.5 s
while the handler waited with await asyncio.sleep(0.5), the ticker ran 9 times
while the handler waited with time.sleep(0.5), the ticker ran 0 times

Three viewers were served at once, on one thread, by your coroutine.

Then press Submit. The next lesson draws the edge of this taste: what a real course in asyncio would add.