diff --git a/doc/src/sgml/ref/listen.sgml b/doc/src/sgml/ref/listen.sgml
index 10a4ef38b1..97cb349a89 100644
--- a/doc/src/sgml/ref/listen.sgml
+++ b/doc/src/sgml/ref/listen.sgml
@@ -10,20 +10,20 @@ LISTEN
LISTEN
-Listen for notification on a relation
+Listen for notification on a notify condition
-1998-09-24
+1998-10-07
-LISTEN classname
+LISTEN notifyname
-1998-09-01
+1998-10-07
Inputs
@@ -33,11 +33,11 @@ Inputs
-classname
+notifyname
-Table object used for notification.
+Name of notify condition.
@@ -62,63 +62,95 @@ Outputs
-LISTEN
+LISTEN
Message returned upon successful completion of registration.
-
+
+
+
+
+
+NOTICE Async_Listen: We are already listening on notifyname
+
+
+
+If this backend is already registered for that notify condition.
+
+
+
+
+
+
-
-
-1998-09-24
+1998-10-07
Description
-LISTEN is used to register the current backend as a listener on the relation
-classname.
-When the command
-NOTIFY classname
-is called either from within a rule or at the query level, the
-frontend applications corresponding to the listening backends
-are notified. When the backend process exits, this registration
-is cleared.
+LISTEN registers the current Postgres backend as a
+listener on the notify condition
+notifyname.
-This event notification is performed through the libpq protocol
-and frontend application interface. The application program
-must call the routine
-PQnotifies
-in order to find out the name of the class to which a given
-notification corresponds. If this code is not included in
-the application, the event notification will be queued and
-never be processed.
+Whenever the command
+NOTIFY notifyname
+is invoked, either by this backend or another one connected to
+the same database, all the backends currently listening on that notify
+condition are notified, and each will in turn notify its connected
+frontend application. See the discussion of NOTIFY
+for more information.
+
+
+A backend can be deregistered for a given notify condition with the
+UNLISTEN command. Also, a backend's listen registrations
+are automatically cleared when the backend process exits.
+
+
+The method a frontend application must use to detect notify events depends on
+which Postgres application programming interface it
+uses. With the basic libpq library, the application issues
+LISTEN as an ordinary SQL command, and then must
+periodically call the routine PQnotifies to find out
+whether any notify events have been received. Other interfaces such as
+libpgtcl provide higher-level methods for handling notify events; indeed,
+with libpgtcl the application programmer should not even issue
+LISTEN or UNLISTEN directly. See the
+documentation for the library you are using for more details.
+
+
+The reference page for NOTIFY contains a more extensive
+discussion of the use of LISTEN and
+NOTIFY.
-1998-09-24
+1998-10-07
Notes
-Note that classname
-needs not to be a valid class name but can be any string valid
- as a name up to 32 characters long.
+notifyname
+can be any string valid as a name;
+it need not correspond to the name of any actual table. If
+notifyname
+is enclosed in double-quotes, it need not even be a syntactically
+valid name, but can be any string up to 31 characters long.
-A restriction in some previous releases of
- Postgres that a
-classname
-which does not correspond to an actual table must be enclosed in double-quotes
-is no longer present.
+In some previous releases of
+Postgres,
+notifyname
+had to be enclosed in double-quotes when it did not correspond to any existing
+table name, even if syntactically valid as a name. That is no longer required.
@@ -128,6 +160,7 @@ Usage
+-- Configure and execute a listen/notify sequence from psql
postgres=> listen virtual;
LISTEN
postgres=> notify virtual;
diff --git a/doc/src/sgml/ref/notify.sgml b/doc/src/sgml/ref/notify.sgml
index f88ac45c28..92310c0d8c 100644
--- a/doc/src/sgml/ref/notify.sgml
+++ b/doc/src/sgml/ref/notify.sgml
@@ -10,22 +10,22 @@ NOTIFY
NOTIFY
-Signals all frontends and backends listening on a class
+Signals all frontends and backends listening on a notify condition
-1998-09-24
+1998-10-07
-NOTIFY classname
+NOTIFY notifyname
-1998-09-24
+1998-10-07
Inputs
@@ -35,11 +35,11 @@ Inputs
-classname
+notifyname
-Table or arbitrary relation class used for notification.
+Notify condition to be signaled.
@@ -47,7 +47,7 @@ Table or arbitrary relation class used for notification.
-1998-09-24
+1998-10-07
Outputs
@@ -69,66 +69,141 @@ NOTIFY
-Notification message from backend.
-
+Acknowledgement that notify command has executed.
+
+
+
+
+
+Notify events
+
+
+
+Events are delivered to listening frontends; whether and how each frontend
+application reacts depends on its programming.
+
+
+
+
+
+
-
-
-1998-09-24
+1998-10-07
Description
- NOTIFY is used to awaken all sessions which have
-previously executed
- LISTEN classname.
- This can be used either within an instance-level rule
-as part of the action body or from a normal query.
+The NOTIFY command sends a notify event to each
+frontend application that has previously executed
+LISTEN notifyname
+for the specified notify condition in the current database.
- When used from within a normal query,
-this can be thought of as interprocess communication (IPC). When
-used from within a rule, this can be thought of as an alert mechanism.
+The information passed to the frontend for a notify event includes the notify
+condition name and the notifying backend process's PID. It is up to the
+database designer to define the condition names that will be used in a given
+database and what each one means.
+
- Note that the mere fact that a NOTIFY has been
- executed does not imply anything in particular about the state
- of the class (e.g., that it has been updated),
- nor does the notification protocol transmit any useful information
- other than the class name.
-Therefore, all NOTIFY does is indicate that some backend
- wishes its peers to
- examine classname
- in some application-specific way.
+Commonly, the notify condition name is the same as the name of some table in
+the database, and the notify event essentially means "I changed this table,
+take a look at it to see what's new". But no such association is enforced by
+the NOTIFY and LISTEN commands. For
+example, a database designer could use several different condition names
+to signal different sorts of changes to a single table.
+
- In fact, classname
- need not be the name of an SQL class at all.
- It is best thought of as a condition name
- that the application programmer selects.
+NOTIFY provides a simple form of signal or
+IPC (interprocess communication) mechanism for a collection of processes
+accessing the same Postgres database.
+Higher-level mechanisms can be built by using tables in the database to
+pass additional data (beyond a mere condition name) from notifier to
+listener(s).
+
- This event notification is performed through the libpq protocol
- and frontend application interface. The application program
- must call the routine PQnotifies
- in order to find out the name of the class to which a given
- notification corresponds.
-If this code is not included in the application,
-the event notification will be
- queued and never be processed.
-
+When NOTIFY is used to signal the occurrence of changes
+to a particular table, a useful programming technique is to put the
+NOTIFY in a rule that is triggered by table updates.
+In this way, notification happens automatically when the table is changed,
+and the application programmer can't accidentally forget to do it.
+
+
+NOTIFY interacts with SQL transactions in some important
+ways. Firstly, if a NOTIFY is executed inside a
+transaction, the notify events are not delivered until and unless the
+transaction is committed. This is appropriate, since if the transaction
+is aborted we would like all the commands within it to have had no effect
+--- including NOTIFY. But it can be disconcerting if one
+is expecting the notify events to be delivered immediately. Secondly, if
+a listening backend receives a notify signal while it is within a transaction,
+the notify event will not be delivered to its connected frontend until just
+after the transaction is completed (either committed or aborted). Again, the
+reasoning is that if a notify were delivered within a transaction that was
+later aborted, one would want the notification to be undone somehow --- but
+the backend cannot "take back" a notify once it has sent it to the frontend.
+So notify events are delivered only between transactions. The upshot of this
+is that applications using NOTIFY for real-time signaling
+should try to keep their transactions short.
+
+
+NOTIFY behaves rather like Unix signals in one important
+respect: if the same notify name is signaled multiple times in quick
+succession, recipients may get only one notify event for several executions
+of NOTIFY. So it is a bad idea to depend on the number
+of notifies received; instead use NOTIFY to wake up
+applications that need to pay attention to something, and use a database
+object (such as a sequence) to keep track of what happened or how many times
+it happened.
+
+
+It is common for a frontend that sends NOTIFY to be
+listening on the same notify name itself. In that case it will get back a
+notify event, just like all the other listening frontends. Depending on the
+application logic, this could result in useless work --- for example,
+re-reading a database table to find the same updates that that frontend just
+wrote out. In Postgres 6.4 and later, it is
+possible to avoid such extra work by noticing whether the notifying backend
+process's PID (supplied in the notify event message) is the same as one's own
+backend's PID (available from libpq). When they are the same, the notify
+event is one's own work bouncing back, and can be ignored. (Despite what was
+said in the preceding paragraph, this is a safe technique.
+Postgres keeps self-notifies separate from notifies
+arriving from other backends, so you cannot miss an outside notify by ignoring
+your own notifies.)
+
-1998-09-24
+1998-10-07
Notes
-
-
+
+notifyname
+can be any string valid as a name;
+it need not correspond to the name of any actual table. If
+notifyname
+is enclosed in double-quotes, it need not even be a syntactically
+valid name, but can be any string up to 31 characters long.
+
+
+In some previous releases of
+Postgres,
+notifyname
+had to be enclosed in double-quotes when it did not correspond to any existing
+table name, even if syntactically valid as a name. That is no longer required.
+
+
+In Postgres releases prior to 6.4, the backend
+PID delivered in a notify message is always the PID of the frontend's own
+backend. So it is not possible to distinguish one's own notifies from other
+clients' notifies in those earlier releases.
@@ -137,19 +212,13 @@ Notes
Usage
-
--- Configure and execute a listen/notify sequence
--- from psql
-CREATE TABLE t (i int4);
-
-LISTEN t;
-
-NOTIFY t;
-
+-- Configure and execute a listen/notify sequence from psql
+postgres=> listen virtual;
+LISTEN
+postgres=> notify virtual;
NOTIFY
-ASYNC NOTIFY of 't' from backend pid '10949' received
-
+ASYNC NOTIFY of 'virtual' from backend pid '11239' received