diff options
| author | Tom Lane <tgl@sss.pgh.pa.us> | 2019-11-24 18:03:39 -0500 |
|---|---|---|
| committer | Tom Lane <tgl@sss.pgh.pa.us> | 2019-11-24 18:03:39 -0500 |
| commit | d3aa114ac4de9ecc558ba77ed5c85e2ad9ad01d4 (patch) | |
| tree | 8346635a53f8ad69ff54fc76ba8c672eb4107632 /doc/src | |
| parent | 6b802cfc7fab0f38001ae465ccd4f7f565b6169d (diff) | |
| download | postgresql-d3aa114ac4de9ecc558ba77ed5c85e2ad9ad01d4.tar.gz postgresql-d3aa114ac4de9ecc558ba77ed5c85e2ad9ad01d4.zip | |
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
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/ref/listen.sgml | 31 |
1 files changed, 24 insertions, 7 deletions
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 <replaceable class="parameter">channel</replaceable> <command>LISTEN</command> or <command>UNLISTEN</command> directly. See the documentation for the interface you are using for more details. </para> - - <para> - <xref linkend="sql-notify"/> - contains a more extensive - discussion of the use of <command>LISTEN</command> and - <command>NOTIFY</command>. - </para> </refsect1> <refsect1> @@ -96,10 +89,34 @@ LISTEN <replaceable class="parameter">channel</replaceable> within a transaction that later rolls back, the set of notification channels being listened to is unchanged. </para> + <para> A transaction that has executed <command>LISTEN</command> cannot be prepared for two-phase commit. </para> + + <para> + 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 <command>LISTEN</command>: 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. + </para> + + <para> + <xref linkend="sql-notify"/> + contains a more extensive + discussion of the use of <command>LISTEN</command> and + <command>NOTIFY</command>. + </para> </refsect1> <refsect1> |