From 873c0fd67872426e88ac07cbb7ae07457416aafa Mon Sep 17 00:00:00 2001
From: Thomas Munro <tmunro@postgresql.org>
Date: Wed, 19 Mar 2025 16:58:06 +1300
Subject: [PATCH] oauth: Improve validator docs on interruptibility

Andres pointed out that EINTR handling is inadequate for real-world use
cases. Direct module writers to our wait APIs instead.

Author: Jacob Champion <jacob.champion@enterprisedb.com>
Discussion: https://postgr.es/m/p4bd7mn6dxr2zdak74abocyltpfdxif4pxqzixqpxpetjwt34h%40qc6jgfmoddvq
---
 doc/src/sgml/oauth-validators.sgml | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/doc/src/sgml/oauth-validators.sgml b/doc/src/sgml/oauth-validators.sgml
index 356f11d3bd8..704089dd7b3 100644
--- a/doc/src/sgml/oauth-validators.sgml
+++ b/doc/src/sgml/oauth-validators.sgml
@@ -209,11 +209,13 @@
       <para>
        Modules must remain interruptible by signals so that the server can
        correctly handle authentication timeouts and shutdown signals from
-       <application>pg_ctl</application>. For example, a module receiving
-       <symbol>EINTR</symbol>/<symbol>EAGAIN</symbol> from a blocking call
-       should call <function>CHECK_FOR_INTERRUPTS()</function> before retrying.
-       The same should be done during any long-running loops. Failure to follow
-       this guidance may result in unresponsive backend sessions.
+       <application>pg_ctl</application>. For example, blocking calls on sockets
+       should generally be replaced with code that handles both socket events
+       and interrupts without races (see <function>WaitLatchOrSocket()</function>,
+       <function>WaitEventSetWait()</function>, et al), and long-running loops
+       should periodically call <function>CHECK_FOR_INTERRUPTS()</function>.
+       Failure to follow this guidance may result in unresponsive backend
+       sessions.
       </para>
      </listitem>
     </varlistentry>