From d3aa114ac4de9ecc558ba77ed5c85e2ad9ad01d4 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Sun, 24 Nov 2019 18:03:39 -0500 Subject: Doc: improve discussion of race conditions involved in LISTEN. The user docs didn't really explain how to use LISTEN safely, so clarify that. Also clean up some fuzzy-headed explanations in comments. No code changes. Discussion: https://postgr.es/m/3ac7f397-4d5f-be8e-f354-440020675694@gmail.com --- doc/src/sgml/ref/listen.sgml | 31 ++++++++++++++++++++++++------- 1 file changed, 24 insertions(+), 7 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/ref/listen.sgml b/doc/src/sgml/ref/listen.sgml index ecc1fb82def..2fab9d65a10 100644 --- a/doc/src/sgml/ref/listen.sgml +++ b/doc/src/sgml/ref/listen.sgml @@ -63,13 +63,6 @@ LISTEN channel LISTEN or UNLISTEN directly. See the documentation for the interface you are using for more details. - - - - contains a more extensive - discussion of the use of LISTEN and - NOTIFY. - @@ -96,10 +89,34 @@ LISTEN channel within a transaction that later rolls back, the set of notification channels being listened to is unchanged. + A transaction that has executed LISTEN cannot be prepared for two-phase commit. + + + There is a race condition when first setting up a listening session: + if concurrently-committing transactions are sending notify events, + exactly which of those will the newly listening session receive? + The answer is that the session will receive all events committed after + an instant during the transaction's commit step. But that is slightly + later than any database state that the transaction could have observed + in queries. This leads to the following rule for + using LISTEN: first execute (and commit!) that + command, then in a new transaction inspect the database state as needed + by the application logic, then rely on notifications to find out about + subsequent changes to the database state. The first few received + notifications might refer to updates already observed in the initial + database inspection, but this is usually harmless. + + + + + contains a more extensive + discussion of the use of LISTEN and + NOTIFY. + -- cgit v1.2.3