ok
Direktori : /opt/alt/postgresql11/usr/share/doc/alt-postgresql11-9.2.24/html/ |
Current File : //opt/alt/postgresql11/usr/share/doc/alt-postgresql11-9.2.24/html/libpq-notify.html |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <HTML ><HEAD ><TITLE >Asynchronous Notification</TITLE ><META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK REV="MADE" HREF="mailto:pgsql-docs@postgresql.org"><LINK REL="HOME" TITLE="PostgreSQL 9.2.24 Documentation" HREF="index.html"><LINK REL="UP" TITLE="libpq - C Library" HREF="libpq.html"><LINK REL="PREVIOUS" TITLE="The Fast-Path Interface" HREF="libpq-fastpath.html"><LINK REL="NEXT" TITLE="Functions Associated with the COPY Command" HREF="libpq-copy.html"><LINK REL="STYLESHEET" TYPE="text/css" HREF="stylesheet.css"><META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1"><META NAME="creation" CONTENT="2017-11-06T22:43:11"></HEAD ><BODY CLASS="SECT1" ><DIV CLASS="NAVHEADER" ><TABLE SUMMARY="Header navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TH COLSPAN="5" ALIGN="center" VALIGN="bottom" ><A HREF="index.html" >PostgreSQL 9.2.24 Documentation</A ></TH ></TR ><TR ><TD WIDTH="10%" ALIGN="left" VALIGN="top" ><A TITLE="The Fast-Path Interface" HREF="libpq-fastpath.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="10%" ALIGN="left" VALIGN="top" ><A HREF="libpq.html" ACCESSKEY="U" >Up</A ></TD ><TD WIDTH="60%" ALIGN="center" VALIGN="bottom" >Chapter 31. <SPAN CLASS="APPLICATION" >libpq</SPAN > - C Library</TD ><TD WIDTH="20%" ALIGN="right" VALIGN="top" ><A TITLE="Functions Associated with the COPY Command" HREF="libpq-copy.html" ACCESSKEY="N" >Next</A ></TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><DIV CLASS="SECT1" ><H1 CLASS="SECT1" ><A NAME="LIBPQ-NOTIFY" >31.8. Asynchronous Notification</A ></H1 ><P > <SPAN CLASS="PRODUCTNAME" >PostgreSQL</SPAN > offers asynchronous notification via the <TT CLASS="COMMAND" >LISTEN</TT > and <TT CLASS="COMMAND" >NOTIFY</TT > commands. A client session registers its interest in a particular notification channel with the <TT CLASS="COMMAND" >LISTEN</TT > command (and can stop listening with the <TT CLASS="COMMAND" >UNLISTEN</TT > command). All sessions listening on a particular channel will be notified asynchronously when a <TT CLASS="COMMAND" >NOTIFY</TT > command with that channel name is executed by any session. A <SPAN CLASS="QUOTE" >"payload"</SPAN > string can be passed to communicate additional data to the listeners. </P ><P > <SPAN CLASS="APPLICATION" >libpq</SPAN > applications submit <TT CLASS="COMMAND" >LISTEN</TT >, <TT CLASS="COMMAND" >UNLISTEN</TT >, and <TT CLASS="COMMAND" >NOTIFY</TT > commands as ordinary SQL commands. The arrival of <TT CLASS="COMMAND" >NOTIFY</TT > messages can subsequently be detected by calling <CODE CLASS="FUNCTION" >PQnotifies</CODE >. </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 channel name */ int be_pid; /* process ID of notifying server process */ char *extra; /* notification payload string */ } PGnotify;</PRE ><P> After processing a <TT CLASS="STRUCTNAME" >PGnotify</TT > 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 <TT CLASS="STRUCTNAME" >PGnotify</TT > pointer; the <TT CLASS="STRUCTFIELD" >relname</TT > and <TT CLASS="STRUCTFIELD" >extra</TT > fields do not represent separate allocations. (The names of these fields are historical; in particular, channel names need not have anything to do with relation names.) </P ><P > <A HREF="libpq-example.html#LIBPQ-EXAMPLE-2" >Example 31-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 <TT CLASS="COMMAND" >NOTIFY</TT > 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 <TT CLASS="COMMAND" >NOTIFY</TT > 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 ><DIV CLASS="NAVFOOTER" ><HR ALIGN="LEFT" WIDTH="100%"><TABLE SUMMARY="Footer navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" ><A HREF="libpq-fastpath.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="index.html" ACCESSKEY="H" >Home</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" ><A HREF="libpq-copy.html" ACCESSKEY="N" >Next</A ></TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" >The Fast-Path Interface</TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="libpq.html" ACCESSKEY="U" >Up</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" >Functions Associated with the <TT CLASS="COMMAND" >COPY</TT > Command</TD ></TR ></TABLE ></DIV ></BODY ></HTML >