On 04/07/2026 01:28, Jelte Fennema-Nio wrote:
The comments you added in your patches help a lot, explaining the three
different ways that cancellation can be handled, thanks for that.
Yeah, I think
I extracted just the comment in fe_utils/cancel.c to a separate patch,
and modified it to reflect the reality before the rest of the changes.
I'm inclined to commit that now to document the status quo. That'll also
make it easier to see what the other patches change. Does the attached
look correct to you?
- Heikki
From 5b62e1b09e233d9b49e438267fe995e840111abf Mon Sep 17 00:00:00 2001
From: Heikki Linnakangas <[email protected]>
Date: Sun, 5 Jul 2026 01:44:42 +0300
Subject: [PATCH 1/1] Add comment to describe the various frontend cancel
methods
Author: Jelte Fennema-Nio <[email protected]>
Discussion: https://www.postgresql.org/message-id/[email protected]
---
src/fe_utils/cancel.c | 34 ++++++++++++++++++++++++++++++++--
1 file changed, 32 insertions(+), 2 deletions(-)
diff --git a/src/fe_utils/cancel.c b/src/fe_utils/cancel.c
index e6b75439f56..9fac04e333e 100644
--- a/src/fe_utils/cancel.c
+++ b/src/fe_utils/cancel.c
@@ -2,9 +2,39 @@
*
* Query cancellation support for frontend code
*
- * Assorted utility functions to control query cancellation with signal
- * handler for SIGINT.
+ * This module provides SIGINT/Ctrl-C handling for frontend tools that need to
+ * cancel queries or interrupt other operations. It provides three
+ * independent mechanisms, any combination of which can be used by an
+ * application:
*
+ * 1. Server cancel query request -- When a query is running and the main
+ * thread is waiting for the result of that query in a blocking manner, we
+ * want SIGINT/Ctrl-C to cancel that query. This can be achieved by
+ * calling SetCancelConn() to register the connection that is (or will be)
+ * running the query, prior to waiting for the result. When SIGINT/Ctrl-C
+ * is received, a cancel request for this connection will then be sent from
+ * the signal handler (on Windows, from a separate thread). That in turn
+ * will then (assuming a co-operating server) cause the server to cancel
+ * the query and send an error to the waiting client on the main thread.
+ * The cancel connection is a process-wide global, so only one connection
+ * can be the cancel target at a time. ResetCancelConn() should be called
+ * to disarm the mechanism again after the blocking wait has completed.
+ *
+ * 2. CancelRequested flag -- The CancelRequested flag is set to true whenever
+ * SIGINT is received, and can be checked by the application at appropriate
+ * times. The primary use case for this is when the application code is
+ * not blocked (indefinitely), but needs to take an action when Ctrl-C is
+ * pressed, such as break out of a long running loop.
+ *
+ * 3. Signal handler callback -- A callback function can be registered with
+ * setup_cancel_handler(), which will then be called directly from the
+ * signal handler whenever SIGINT is received. Because it is called from a
+ * signal handler, the callback function must be async-signal-safe. On
+ * Windows, it is called from a separate signal-handling thread. NOTE: The
+ * callback is called AFTER setting CancelRequested but BEFORE sending the
+ * cancel request to the server (if armed by SetCancelConn). This means
+ * that if the callback exits or longjmps, no cancel request will be sent
+ * to the server.
*
* Portions Copyright (c) 1996-2026, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
--
2.47.3
