Skip to content

Commit 55a5639

Browse files
tglsfdctglsfdc
committed
LISTEN/NOTIFY doc improvements.
1 parent 30debec commit 55a5639

File tree

2 files changed

+194
-92
lines changed

2 files changed

+194
-92
lines changed

‎doc/src/sgml/ref/listen.sgml

Lines changed: 69 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -10,20 +10,20 @@ LISTEN
1010
LISTEN
1111
</REFNAME>
1212
<REFPURPOSE>
13-
Listen for notification on a relation
13+
Listen for notification on a notify condition
1414
</REFPURPOSE>
1515

1616
<REFSYNOPSISDIV>
1717
<REFSYNOPSISDIVINFO>
18-
<DATE>1998-09-24</DATE>
18+
<DATE>1998-10-07</DATE>
1919
</REFSYNOPSISDIVINFO>
2020
<SYNOPSIS>
21-
LISTEN <REPLACEABLE CLASS="PARAMETER">classname</REPLACEABLE>
21+
LISTEN <REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
2222
</SYNOPSIS>
2323

2424
<REFSECT2 ID="R2-SQL-LISTEN-1">
2525
<REFSECT2INFO>
26-
<DATE>1998-09-01</DATE>
26+
<DATE>1998-10-07</DATE>
2727
</REFSECT2INFO>
2828
<TITLE>
2929
Inputs
@@ -33,11 +33,11 @@ Inputs
3333
<VARIABLELIST>
3434
<VARLISTENTRY>
3535
<TERM>
36-
<REPLACEABLE CLASS="PARAMETER">classname</REPLACEABLE>
36+
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
3737
</TERM>
3838
<LISTITEM>
3939
<PARA>
40-
Table object used for notification.
40+
Name of notify condition.
4141

4242
</VARIABLELIST>
4343

@@ -62,63 +62,95 @@ Outputs
6262
<VARIABLELIST>
6363
<VARLISTENTRY>
6464
<TERM>
65-
LISTEN
65+
<returnvalue>LISTEN</returnvalue>
6666
</TERM>
6767
<LISTITEM>
6868
<PARA>
6969
Message returned upon successful completion of registration.
70-
71-
</VARIABLELIST>
70+
</PARA>
71+
</LISTITEM>
72+
</VARLISTENTRY>
73+
<VARLISTENTRY>
74+
<TERM>
75+
<returnvalue>NOTICE Async_Listen: We are already listening on notifyname</returnvalue>
76+
</TERM>
77+
<LISTITEM>
78+
<PARA>
79+
If this backend is already registered for that notify condition.
80+
</PARA>
81+
</LISTITEM>
82+
</VARLISTENTRY>
83+
</variablelist>
84+
</LISTITEM>
85+
</VARLISTENTRY>
7286
</VARIABLELIST>
73-
7487
</REFSECT2>
7588
</REFSYNOPSISDIV>
7689

7790
<REFSECT1 ID="R1-SQL-LISTEN-1">
7891
<REFSECT1INFO>
79-
<DATE>1998-09-24</DATE>
92+
<DATE>1998-10-07</DATE>
8093
</REFSECT1INFO>
8194
<TITLE>
8295
Description
8396
</TITLE>
8497
<PARA>
85-
LISTEN is used to register the current backend as a listener on the relation
86-
<REPLACEABLE CLASS="PARAMETER">classname</REPLACEABLE>.
87-
When the command
88-
<command>NOTIFY <REPLACEABLE CLASS="PARAMETER">classname</REPLACEABLE></command>
89-
is called either from within a rule or at the query level, the
90-
frontend applications corresponding to the listening backends
91-
are notified. When the backend process exits, this registration
92-
is cleared.
98+
LISTEN registers the current <productname>Postgres</productname> backend as a
99+
listener on the notify condition
100+
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>.
101+
102+
<para>
103+
Whenever the command
104+
<command>NOTIFY <REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE></command>
105+
is invoked, either by this backend or another one connected to
106+
the same database, all the backends currently listening on that notify
107+
condition are notified, and each will in turn notify its connected
108+
frontend application. See the discussion of <command>NOTIFY</command>
109+
for more information.
93110

94111
<para>
95-
This event notification is performed through the libpq protocol
96-
and frontend application interface. The application program
97-
must call the routine
98-
<function>PQnotifies</function>
99-
in order to find out the name of the class to which a given
100-
notification corresponds. If this code is not included in
101-
the application, the event notification will be queued and
102-
never be processed.
112+
A backend can be deregistered for a given notify condition with the
113+
<command>UNLISTEN</command> command. Also, a backend's listen registrations
114+
are automatically cleared when the backend process exits.
115+
116+
<para>
117+
The method a frontend application must use to detect notify events depends on
118+
which <productname>Postgres</productname> application programming interface it
119+
uses. With the basic libpq library, the application issues
120+
<command>LISTEN</command> as an ordinary SQL command, and then must
121+
periodically call the routine <function>PQnotifies</function> to find out
122+
whether any notify events have been received. Other interfaces such as
123+
libpgtcl provide higher-level methods for handling notify events; indeed,
124+
with libpgtcl the application programmer should not even issue
125+
<command>LISTEN</command> or <command>UNLISTEN</command> directly. See the
126+
documentation for the library you are using for more details.
127+
128+
<para>
129+
The reference page for <command>NOTIFY</command> contains a more extensive
130+
discussion of the use of <command>LISTEN</command> and
131+
<command>NOTIFY</command>.
103132

104133
<REFSECT2 ID="R2-SQL-LISTEN-3">
105134
<REFSECT2INFO>
106-
<DATE>1998-09-24</DATE>
135+
<DATE>1998-10-07</DATE>
107136
</REFSECT2INFO>
108137
<TITLE>
109138
Notes
110139
</TITLE>
111140
<para>
112-
Note that <REPLACEABLE CLASS="PARAMETER">classname</REPLACEABLE>
113-
needs not to be a valid class name but can be any string valid
114-
as a name up to 32 characters long.
141+
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
142+
can be any string valid as a name;
143+
it need not correspond to the name of any actual table. If
144+
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
145+
is enclosed in double-quotes, it need not even be a syntactically
146+
valid name, but can be any string up to 31 characters long.
115147

116148
<para>
117-
A restriction in some previous releases of
118-
<productname>Postgres</productname> that a
119-
<REPLACEABLE CLASS="PARAMETER">classname</REPLACEABLE>
120-
which does not correspond to an actual table must be enclosed in double-quotes
121-
is no longer present.
149+
In some previous releases of
150+
<productname>Postgres</productname>,
151+
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
152+
had to be enclosed in double-quotes when it did not correspond to any existing
153+
table name, even if syntactically valid as a name. That is no longer required.
122154

123155
</REFSECT2>
124156

@@ -128,6 +160,7 @@ Usage
128160
</TITLE>
129161
<PARA>
130162
<ProgramListing>
163+
-- Configure and execute a listen/notify sequence from psql
131164
postgres=> listen virtual;
132165
LISTEN
133166
postgres=> notify virtual;

0 commit comments

Comments
 (0)