Update documentation related to async and Ctrl-C

Now that #543 is fixed, users shouldn't need to manually set up
signal handlers to cancel operations any more.  Update the documentation
to reflect this.

diff --git a/docs/advanced/async.rst b/docs/advanced/async.rst
index 3620ab6814118a50f3d9b2a44a8661f5179ba62b..dfb9fabc59750c92510c406a200c67b697ddc98e 100644 (file)
--- a/docs/advanced/async.rst
+++ b/docs/advanced/async.rst
@@ -113,30 +113,32 @@ you can use the normal `async with` context manager.
 
 .. _async-ctrl-c:
 
-Interrupting async operations using Ctrl-C
-------------------------------------------
+Interrupting async operations
+-----------------------------
 
 If a long running operation is interrupted by a Ctrl-C on a normal connection
 running in the main thread, the operation will be cancelled and the connection
 will be put in error state, from which can be recovered with a normal
 `~Connection.rollback()`.
 
-If the query is running in an async connection, a Ctrl-C will be likely
-intercepted by the async loop and interrupt the whole program. In order to
-emulate what normally happens with blocking connections, you can use
-`asyncio's add_signal_handler()`__, to call `Connection.cancel()`:
+An async connection provides similar behavior in that if the async task is
+cancelled, any operation on the connection will similarly be cancelled.  This
+can happen either indirectly via Ctrl-C or similar signal, or directly by
+cancelling the Python Task via the normal way.  Psycopg will ask the
+PostgreSQL postmaster to cancel the operation when it encounters the standard
+Python `CancelledError`__.
 
-.. code:: python
-
-    import asyncio
-    import signal
+Remember that cancelling the Python Task does not guarantee that the operation
+will not complete, even if the task ultimately exits prematurely due to
+CancelledError.  If you need to know the ultimate outcome of the statement,
+then consider calling `Connection.cancel()` as an alternative to cancelling
+the task.
 
-    async with await psycopg.AsyncConnection.connect() as conn:
-        loop.add_signal_handler(signal.SIGINT, conn.cancel)
-        ...
+Previous versions of Psycopg recommended setting up signal handlers to
+manually cancel connections.  This should no longer be necessary.
 
 
-.. __: https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.loop.add_signal_handler
+.. __: https://docs.python.org/3/library/asyncio-task.html#task-cancellation
 
 
 .. index::