1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>28.7.Asynchronous Notification</title>
<link rel="stylesheet" href="stylesheet.css" type="text/css">
<link rev="made" href="pgsql-docs@postgresql.org">
<meta name="generator" content="DocBook XSL Stylesheets V1.70.0">
<link rel="start" href="index.html" title="PostgreSQL 8.1.4 Documentation">
<link rel="up" href="libpq.html" title="Chapter28.libpq - C Library">
<link rel="prev" href="libpq-fastpath.html" title="28.6.The Fast-Path Interface">
<link rel="next" href="libpq-copy.html" title="28.8.Functions Associated with the COPY Command">
<link rel="copyright" href="ln-legalnotice.html" title="Legal Notice">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="sect1" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="libpq-notify"></a>28.7.Asynchronous Notification</h2></div></div></div>
<a name="id683564"></a><p><span class="productname">PostgreSQL</span> offers asynchronous notification via the
<code class="command">LISTEN</code> and <code class="command">NOTIFY</code> commands. A client session registers its interest in a particular
notification condition with the <code class="command">LISTEN</code> command (and can stop listening
with the <code class="command">UNLISTEN</code> command). All sessions listening on a
particular condition will be notified asynchronously when a <code class="command">NOTIFY</code> command with that
condition name is executed by any session. No additional information is
passed from the notifier to the listener. Thus, typically, any actual data
that needs to be communicated is transferred through a database table.
Commonly, the condition name is the same as the associated table, but it is
not necessary for there to be any associated table.</p>
<p><span class="application">libpq</span> applications submit
<code class="command">LISTEN</code> and <code class="command">UNLISTEN</code> commands as
ordinary SQL commands. The arrival of <code class="command">NOTIFY</code>
messages can subsequently be detected by calling
<code class="function">PQnotifies</code>.<a name="id683663"></a></p>
<p>The function <code class="function">PQnotifies</code>
returns the next notification from a list of unhandled
notification messages received from the server. It returns a null pointer if
there are no pending notifications. Once a notification is
returned from <code class="function">PQnotifies</code>, it is considered handled and will be
removed from the list of notifications.
</p>
<pre class="synopsis">PGnotify *PQnotifies(PGconn *conn);
typedef struct pgNotify {
char *relname; /* notification condition name */
int be_pid; /* process ID of server process */
char *extra; /* notification parameter */
} PGnotify;</pre>
<p>
After processing a <code class="structname">PGnotify</code> object returned by
<code class="function">PQnotifies</code>, be sure to free it with
<code class="function">PQfreemem</code>. It is sufficient to free the
<code class="structname">PGnotify</code> pointer; the
<code class="structfield">relname</code> and <code class="structfield">extra</code> fields
do not represent separate allocations.
(At present, the <code class="structfield">extra</code> field is unused and will
always point to an empty string.)</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p> In <span class="productname">PostgreSQL</span> 6.4 and later,
the <code class="structfield">be_pid</code> is that of the notifying server process,
whereas in earlier versions it was always the <acronym class="acronym">PID</acronym> of your own server process.</p>
</div>
<p><a href="libpq-example.html#libpq-example-2" title="Example28.2.libpq Example Program 2">Example28.2, “<span class="application">libpq</span> Example Program 2”</a> gives a sample program that illustrates the use
of asynchronous notification.</p>
<p><code class="function">PQnotifies</code> does not actually read data from the server; it just
returns messages previously absorbed by another <span class="application">libpq</span>
function. In prior releases of <span class="application">libpq</span>, the only way
to ensure timely receipt of <code class="command">NOTIFY</code> messages was to constantly submit commands,
even empty ones, and then check <code class="function">PQnotifies</code> after each
<code class="function">PQexec</code>. While this still works, it is
deprecated as a waste of processing power.</p>
<p>A better way to check for <code class="command">NOTIFY</code>
messages when you have no useful commands to execute is to call
<code class="function">PQconsumeInput</code>, then check
<code class="function">PQnotifies</code>.
You can use <code class="function">select()</code> to wait for data to
arrive from the server, thereby using no <acronym class="acronym">CPU</acronym> power unless there is something
to do. (See <code class="function">PQsocket</code> to obtain the file descriptor
number to use with <code class="function">select()</code>.)
Note that this will work OK whether you submit commands with
<code class="function">PQsendQuery</code>/<code class="function">PQgetResult</code> or simply
use <code class="function">PQexec</code>. You should, however, remember to
check <code class="function">PQnotifies</code> after each
<code class="function">PQgetResult</code> or <code class="function">PQexec</code>, to see
if any notifications came in during the processing of the command.</p>
</div></body>
</html>
|