Document how to shut down the server.

Fix #124, #103.

Author: aaugustin

docs/deployment.rst

@@ -4,9 +4,39 @@ Deployment
 The author of ``websockets`` isn't aware of best practices for deploying
 network services based on :mod:`asyncio`.
 
-He suggests running a Python script similar to the :ref:`server example
-<server-example>`, perhaps inside a supervisor if you deem it useful.
+You can run a script similar to the :ref:`server example <server-example>`,
+inside a supervisor if you deem that useful.
+
+You can also add a wrapper to daemonize the process. Third-party libraries
+provide solutions for that.
 
 If you can share knowledge on this topic, please file an issue_. Thanks!
 
 .. _issue: https://github.com/aaugustin/websockets/issues/new
+
+Graceful shutdown
+-----------------
+
+You may want to close connections gracefully when shutting down the server,
+perhaps after executing some cleanup logic.
+
+The proper way to do this is to call the ``close()`` method of the object
+returned by :func:`~websockets.server.serve`, then wait for ``wait_closed()``
+to complete.
+
+Tasks that handle connections will be cancelled, in the sense that
+:meth:`~websockets.protocol.WebSocketCommonProtocol.recv` raises
+:exc:`~asyncio.CancelledError`.
+
+On Unix systems, shutdown is usually triggered by sending a signal.
+
+Here's a full example (Unix-only):
+
+.. literalinclude:: ../example/shutdown.py
+
+
+It's more difficult to achieve the same effect on Windows. Some third-party
+projects try to help with this problem.
+
+If your server doesn't run in the main thread, look at
+:func:`~asyncio.AbstractEventLoop.call_soon_threadsafe`.

example/client.py

@@ -5,7 +5,7 @@
 
 async def hello():
     async with websockets.connect('ws://localhost:8765') as websocket:
-
+      while True:
         name = input("What's your name? ")
         await websocket.send(name)
         print("> {}".format(name))

example/shutdown.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python
+
+import asyncio
+import signal
+import websockets
+
+async def echo(websocket, path):
+    while True:
+        try:
+            msg = await websocket.recv()
+        except websockets.ConnectionClosed:
+            pass
+        else:
+            await websocket.send(msg)
+
+loop = asyncio.get_event_loop()
+
+# Create the server.
+start_server = websockets.serve(echo, 'localhost', 8765)
+server = loop.run_until_complete(start_server)
+
+# Run the server until SIGTERM.
+stop_server = asyncio.Future()
+loop.add_signal_handler(signal.SIGTERM, stop_server.set_result, None)
+loop.run_until_complete(stop_server)
+
+# Shut down the server.
+server.close()
+loop.run_until_complete(server.wait_closed())