begriffs open source - ai-pg/blob - full-docs/txt/libpq-notify.txt

   1
   2 32.9. Asynchronous Notification #
   3
   4    PostgreSQL offers asynchronous notification via the LISTEN and NOTIFY
   5    commands. A client session registers its interest in a particular
   6    notification channel with the LISTEN command (and can stop listening
   7    with the UNLISTEN command). All sessions listening on a particular
   8    channel will be notified asynchronously when a NOTIFY command with that
   9    channel name is executed by any session. A “payload” string can be
  10    passed to communicate additional data to the listeners.
  11
  12    libpq applications submit LISTEN, UNLISTEN, and NOTIFY commands as
  13    ordinary SQL commands. The arrival of NOTIFY messages can subsequently
  14    be detected by calling PQnotifies.
  15
  16    The function PQnotifies returns the next notification from a list of
  17    unhandled notification messages received from the server. It returns a
  18    null pointer if there are no pending notifications. Once a notification
  19    is returned from PQnotifies, it is considered handled and will be
  20    removed from the list of notifications.
  21 PGnotify *PQnotifies(PGconn *conn);
  22
  23 typedef struct pgNotify
  24 {
  25     char *relname;              /* notification channel name */
  26     int  be_pid;                /* process ID of notifying server process */
  27     char *extra;                /* notification payload string */
  28 } PGnotify;
  29
  30    After processing a PGnotify object returned by PQnotifies, be sure to
  31    free it with PQfreemem. It is sufficient to free the PGnotify pointer;
  32    the relname and extra fields do not represent separate allocations.
  33    (The names of these fields are historical; in particular, channel names
  34    need not have anything to do with relation names.)
  35
  36    Example 32.2 gives a sample program that illustrates the use of
  37    asynchronous notification.
  38
  39    PQnotifies does not actually read data from the server; it just returns
  40    messages previously absorbed by another libpq function. In ancient
  41    releases of libpq, the only way to ensure timely receipt of NOTIFY
  42    messages was to constantly submit commands, even empty ones, and then
  43    check PQnotifies after each PQexec. While this still works, it is
  44    deprecated as a waste of processing power.
  45
  46    A better way to check for NOTIFY messages when you have no useful
  47    commands to execute is to call PQconsumeInput , then check PQnotifies.
  48    You can use select() to wait for data to arrive from the server,
  49    thereby using no CPU power unless there is something to do. (See
  50    PQsocket to obtain the file descriptor number to use with select().)
  51    Note that this will work OK whether you submit commands with
  52    PQsendQuery/PQgetResult or simply use PQexec. You should, however,
  53    remember to check PQnotifies after each PQgetResult or PQexec, to see
  54    if any notifications came in during the processing of the command.