Extract patterns to a howto guide.

Improve this guide.

Fix #1022.

Author: aaugustin

docs/howto/index.rst

@@ -8,6 +8,7 @@ If you're stuck, perhaps you'll find the answer here.
 
    faq
    cheatsheet
+   patterns
    autoreload
 
 This guide will help you integrate websockets into a broader system.

docs/howto/patterns.rst

@@ -0,0 +1,110 @@
+Patterns
+========
+
+.. currentmodule:: websockets
+
+Here are typical patterns for processing messages in a WebSocket server or
+client. You will certainly implement some of them in your application.
+
+This page gives examples of connection handlers for a server. However, they're
+also applicable to a client, simply by assuming that ``websocket`` is a
+connection created with :func:`~client.connect`.
+
+WebSocket connections are long-lived. You will usually write a loop to process
+several messages during the lifetime of a connection.
+
+Consumer
+--------
+
+To receive messages from the WebSocket connection::
+
+    async def consumer_handler(websocket):
+        async for message in websocket:
+            await consumer(message)
+
+In this example, ``consumer()`` is a coroutine implementing your business
+logic for processing a message received on the WebSocket connection. Each
+message may be :class:`str` or :class:`bytes`.
+
+Iteration terminates when the client disconnects.
+
+Producer
+--------
+
+To send messages to the WebSocket connection::
+
+    async def producer_handler(websocket):
+        while True:
+            message = await producer()
+            await websocket.send(message)
+
+In this example, ``producer()`` is a coroutine implementing your business
+logic for generating the next message to send on the WebSocket connection.
+Each message must be :class:`str` or :class:`bytes`.
+
+Iteration terminates when the client disconnects
+because :meth:`~server.WebSocketServerProtocol.send` raises a
+:exc:`~exceptions.ConnectionClosed` exception,
+which breaks out of the ``while  True`` loop.
+
+Consumer and producer
+---------------------
+
+You can receive and send messages on the same WebSocket connection by
+combining the consumer and producer patterns. This requires running two tasks
+in parallel::
+
+    async def handler(websocket):
+        await asyncio.gather(
+            consumer_handler(websocket),
+            producer_handler(websocket),
+        )
+
+If a task terminates, :func:`~asyncio.gather` doesn't cancel the other task.
+This can result in a situation where the producer keeps running after the
+consumer finished, which may leak resources.
+
+Here's a way to exit and close the WebSocket connection as soon as a task
+terminates, after canceling the other task::
+
+    async def handler(websocket):
+        consumer_task = asyncio.create_task(consumer_handler(websocket))
+        producer_task = asyncio.create_task(producer_handler(websocket))
+        done, pending = await asyncio.wait(
+            [consumer_task, producer_task],
+            return_when=asyncio.FIRST_COMPLETED,
+        )
+        for task in pending:
+            task.cancel()
+
+Registration
+------------
+
+To keep track of currently connected clients, you can register them when they
+connect and unregister them when they disconnect::
+
+    connected = set()
+
+    async def handler(websocket):
+        # Register.
+        connected.add(websocket)
+        try:
+            # Broadcast a message to all connected clients.
+            websockets.broadcast(connected, "Hello!")
+            await asyncio.sleep(10)
+        finally:
+            # Unregister.
+            connected.remove(websocket)
+
+This example maintains the set of connected clients in memory. This works as
+long as you run a single process. It doesn't scale to multiple processes.
+
+Publish–subscribe
+-----------------
+
+If you plan to run multiple processes and you want to communicate updates
+between processes, then you must deploy a messaging system. You may find
+publish-subscribe functionality useful.
+
+A complete implementation of this idea with Redis is described in
+the :doc:`Django integration guide <../howto/django>`.

docs/intro/index.rst

@@ -118,85 +118,3 @@ Then open this HTML file in several browsers.
 
 .. literalinclude:: ../../example/counter.html
    :language: html
-
-Common patterns
----------------
-
-You will usually want to process several messages during the lifetime of a
-connection. Therefore you must write a loop. Here are the basic patterns for
-building a WebSocket server.
-
-Consumer
-........
-
-For receiving messages and passing them to a ``consumer`` coroutine::
-
-    async def consumer_handler(websocket):
-        async for message in websocket:
-            await consumer(message)
-
-In this example, ``consumer`` represents your business logic for processing
-messages received on the WebSocket connection.
-
-Iteration terminates when the client disconnects.
-
-Producer
-........
-
-For getting messages from a ``producer`` coroutine and sending them::
-
-    async def producer_handler(websocket):
-        while True:
-            message = await producer()
-            await websocket.send(message)
-
-In this example, ``producer`` represents your business logic for generating
-messages to send on the WebSocket connection.
-
-:meth:`~legacy.protocol.WebSocketCommonProtocol.send` raises a
-:exc:`~exceptions.ConnectionClosed` exception when the client disconnects,
-which breaks out of the ``while True`` loop.
-
-Both sides
-..........
-
-You can read and write messages on the same connection by combining the two
-patterns shown above and running the two tasks in parallel::
-
-    async def handler(websocket):
-        consumer_task = asyncio.ensure_future(
-            consumer_handler(websocket))
-        producer_task = asyncio.ensure_future(
-            producer_handler(websocket))
-        done, pending = await asyncio.wait(
-            [consumer_task, producer_task],
-            return_when=asyncio.FIRST_COMPLETED,
-        )
-        for task in pending:
-            task.cancel()
-
-Registration
-............
-
-As shown in the synchronization example above, if you need to maintain a list
-of currently connected clients, you must register them when they connect and
-unregister them when they disconnect.
-
-::
-
-    connected = set()
-
-    async def handler(websocket):
-        # Register.
-        connected.add(websocket)
-        try:
-            # Broadcast a message to all connected clients.
-            websockets.broadcast(connected, "Hello!")
-            await asyncio.sleep(10)
-        finally:
-            # Unregister.
-            connected.remove(websocket)
-
-This simplistic example keeps track of connected clients in memory. This only
-works as long as you run a single process. In a practical application, the
-handler may subscribe to some channels on a message broker, for example.