From 55a5639e93ef283b511cece5cfc6589bf4e6aaa5 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Thu, 8 Oct 1998 00:18:31 +0000 Subject: [PATCH] LISTEN/NOTIFY doc improvements. --- doc/src/sgml/ref/listen.sgml | 105 +++++++++++++------- doc/src/sgml/ref/notify.sgml | 181 ++++++++++++++++++++++++----------- 2 files changed, 194 insertions(+), 92 deletions(-) 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 <VARIABLELIST> <VARLISTENTRY> <TERM> -<REPLACEABLE CLASS="PARAMETER">classname</REPLACEABLE> +<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE> </TERM> <LISTITEM> <PARA> -Table object used for notification. +Name of notify condition. </VARIABLELIST> @@ -62,63 +62,95 @@ Outputs <VARIABLELIST> <VARLISTENTRY> <TERM> -LISTEN +<returnvalue>LISTEN</returnvalue> </TERM> <LISTITEM> <PARA> Message returned upon successful completion of registration. - -</VARIABLELIST> +</PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM> +<returnvalue>NOTICE Async_Listen: We are already listening on notifyname</returnvalue> +</TERM> +<LISTITEM> +<PARA> +If this backend is already registered for that notify condition. +</PARA> +</LISTITEM> +</VARLISTENTRY> +</variablelist> +</LISTITEM> +</VARLISTENTRY> </VARIABLELIST> - </REFSECT2> </REFSYNOPSISDIV> <REFSECT1 ID="R1-SQL-LISTEN-1"> <REFSECT1INFO> -<DATE>1998-09-24</DATE> +<DATE>1998-10-07</DATE> </REFSECT1INFO> <TITLE> 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. + + +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. -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. +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 <VARIABLELIST> <VARLISTENTRY> <TERM> -<REPLACEABLE CLASS="PARAMETER">classname</REPLACEABLE> +<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE> </TERM> <LISTITEM> <PARA> -Table or arbitrary relation class used for notification. +Notify condition to be signaled. </VARIABLELIST> @@ -47,7 +47,7 @@ Table or arbitrary relation class used for notification. <REFSECT2 ID="R2-SQL-NOTIFY-2"> <REFSECT2INFO> -<DATE>1998-09-24</DATE> +<DATE>1998-10-07</DATE> </REFSECT2INFO> <TITLE> Outputs @@ -69,66 +69,141 @@ NOTIFY </TERM> <LISTITEM> <PARA> -Notification message from backend. - -</VARIABLELIST> +Acknowledgement that notify command has executed. +</PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM> +Notify events +</TERM> +<LISTITEM> +<PARA> +Events are delivered to listening frontends; whether and how each frontend +application reacts depends on its programming. +</PARA> +</LISTITEM> +</VARLISTENTRY> +</variablelist> +</LISTITEM> +</VARLISTENTRY> </VARIABLELIST> - </REFSECT2> </REFSYNOPSISDIV> <REFSECT1 ID="R1-SQL-NOTIFY-1"> <REFSECT1INFO> -<DATE>1998-09-24</DATE> +<DATE>1998-10-07</DATE> </REFSECT1INFO> <TITLE> 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 -- 2.40.0