diff options
Diffstat (limited to 'src/bin/pgaccess/lib/help/notify.hlp')
-rw-r--r-- | src/bin/pgaccess/lib/help/notify.hlp | 57 |
1 files changed, 0 insertions, 57 deletions
diff --git a/src/bin/pgaccess/lib/help/notify.hlp b/src/bin/pgaccess/lib/help/notify.hlp deleted file mode 100644 index 9185f23ef6b..00000000000 --- a/src/bin/pgaccess/lib/help/notify.hlp +++ /dev/null @@ -1,57 +0,0 @@ -.pgaw:Help.f.t insert end "NOTIFY" {bold} " 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. - -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. - -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. - -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). - -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 only delivered between \ -transactions. The upshot of this is that applications using NOTIFY for real-time signaling should try to keep their transactions short. - -NOTIFY behaves like Unix signals in one important respect: if the same condition 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.) - -" {} "Synopsis" {bold} " - -NOTIFY notifyname - -" {} "Usage" {bold} " - - -- Configure and execute a listen/notify sequence from psql -" {} " postgres=> listen virtual; - LISTEN - postgres=> notify virtual; - NOTIFY - ASYNC NOTIFY of 'virtual' from backend pid '11239' received - -" {code} "Notes" {bold} " - -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 was always the PID of the frontend's own backend. So it was not possible to distinguish one's own notifies from \ -other clients' notifies in those earlier releases. " |