Skip to content

Commit 5838918

Browse files
bmomjianbmomjian
committed
The attached patch modifies libpgtcl per previous discussion: the
pg_notifies statement is eliminated, and callbacks defined by pg_listen are instead invoked automatically from the Tcl idle loop whenever a NOTIFY message is received. I have done only cursory testing, so there may be problems still lurking (particularly on non-Unix machines?). But it seems to work. Patch is against today's cvs sources. Note that this will not work with the 6.3.2 release since it depends on the new libpq. The diffs are a bit large so I've gzipped them. A patch to update libpgtcl.sgml is included too. regards, tom lane
1 parent 693b156 commit 5838918

File tree

6 files changed

+548
-171
lines changed

6 files changed

+548
-171
lines changed

‎doc/src/sgml/libpgtcl.sgml

Lines changed: 123 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,8 @@
33

44
<Para>
55
pgtcl is a tcl package for front-end programs to interface with <ProductName>Postgres</ProductName>
6-
backends. pgtcl does not use the libpq library but communicates to
7-
the backend directly via the frontend-backend protocol. Thus, it is
8-
more efficient than previous postgres->tcl bindings which are layered
9-
on top of libpq. In addition, pgtcl can handle multiple backend
10-
connections from a single frontend application.
6+
backends. It makes most of the functionality of libpq available to
7+
tcl scripts.
118
</Para>
129

1310
<Para>
@@ -42,17 +39,25 @@ the standard Unix file system interface.
4239
<ENTRY>pg_disconnect</ENTRY>
4340
<ENTRY>closes a connection</ENTRY>
4441
</ROW>
42+
<ROW>
43+
<ENTRY>pg_conndefaults</ENTRY>
44+
<ENTRY>get connection options and their defaults</ENTRY>
45+
</ROW>
4546
<ROW>
4647
<ENTRY>pg_exec</ENTRY>
4748
<ENTRY>send a query to the backend</ENTRY>
4849
</ROW>
50+
<ROW>
51+
<ENTRY>pg_result</ENTRY>
52+
<ENTRY>manipulate the results of a query</ENTRY>
53+
</ROW>
4954
<ROW>
5055
<ENTRY>pg_select</ENTRY>
5156
<ENTRY>loop over the result of a select statement</ENTRY>
5257
</ROW>
5358
<ROW>
54-
<ENTRY>pg_result</ENTRY>
55-
<ENTRY>manipulate the results of a query</ENTRY>
59+
<ENTRY>pg_listen</ENTRY>
60+
<ENTRY>establish a callback for NOTIFY messages</ENTRY>
5661
</ROW>
5762

5863
<ROW>
@@ -101,8 +106,7 @@ the standard Unix file system interface.
101106
</Para>
102107

103108
<Para>
104-
Some commands equivalent to libpq commands are provided for connection
105-
and query operations.
109+
These commands are described further on subsequent pages.
106110
</Para>
107111

108112
<Para>
@@ -142,7 +146,7 @@ proc getDBs { {host "localhost"} {port "5432"} } {
142146
</Sect1>
143147

144148
<Sect1>
145-
<Title>Reference Information</Title>
149+
<Title>pgtcl Command Reference Information</Title>
146150

147151
<REFENTRY ID="PGTCL-PGCONNECT-1">
148152
<REFMETA>
@@ -235,7 +239,7 @@ pg_connect <REPLACEABLE CLASS="PARAMETER">dbName</REPLACEABLE> <OPTIONAL>-host <
235239
<LISTITEM>
236240
<PARA>
237241
The return result is either an error message or a handle for a database
238-
connection. Handles start with the prefix "pgp"
242+
connection. Handles start with the prefix "pgsql"
239243
</PARA>
240244
</LISTITEM>
241245
</VARLISTENTRY>
@@ -414,7 +418,114 @@ pg_exec <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE> <REPLACEABLE CLASS
414418
</TITLE>
415419
<PARA>
416420
<FUNCTION>pg_exec</FUNCTION> submits a query to the <ProductName>Postgres</ProductName> backend and returns a result.
417-
Handles start with the prefix "pgp".
421+
422+
Query result handles start with the connection handle and add a period
423+
and a result number.
424+
</PARA>
425+
</REFSECT1>
426+
427+
<REFENTRY ID="PGTCL-PGLISTEN-1">
428+
<REFMETA>
429+
<REFENTRYTITLE>pg_listen</REFENTRYTITLE>
430+
<REFMISCINFO>PGTCL - Asynchronous Notify</REFMISCINFO>
431+
</REFMETA>
432+
<REFNAMEDIV>
433+
<REFNAME>pg_listen
434+
</REFNAME>
435+
<REFPURPOSE>sets or changes a callback for asynchronous NOTIFY messages
436+
</REFPURPOSE>
437+
<INDEXTERM ID="IX-PGTCL-PGLISTEN-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>notify</SECONDARY></INDEXTERM>
438+
<INDEXTERM ID="IX-PGTCL-PGLISTEN-2"><PRIMARY>notify</PRIMARY></INDEXTERM>
439+
</REFNAMEDIV>
440+
<REFSYNOPSISDIV>
441+
<REFSYNOPSISDIVINFO>
442+
<DATE>1998-5-22</DATE>
443+
</REFSYNOPSISDIVINFO>
444+
<SYNOPSIS>
445+
pg_listen <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">notifyName</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">callbackCommand</REPLACEABLE>
446+
</SYNOPSIS>
447+
448+
<REFSECT2 ID="R2-PGTCL-PGLISTEN-1">
449+
<REFSECT2INFO>
450+
<DATE>1998-5-22</DATE>
451+
</REFSECT2INFO>
452+
<TITLE>Inputs
453+
</TITLE>
454+
<VARIABLELIST>
455+
<VARLISTENTRY>
456+
<TERM>
457+
<REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE>
458+
</TERM>
459+
<LISTITEM>
460+
<PARA>Specifies a valid database handle.
461+
</PARA>
462+
</LISTITEM>
463+
</VARLISTENTRY>
464+
<VARLISTENTRY>
465+
<TERM>
466+
<REPLACEABLE CLASS="PARAMETER">notifyName</REPLACEABLE>
467+
</TERM>
468+
<LISTITEM>
469+
<PARA>Specifies the notification name to start or stop listening to.
470+
</PARA>
471+
</LISTITEM>
472+
</VARLISTENTRY>
473+
<VARLISTENTRY>
474+
<TERM>
475+
<REPLACEABLE CLASS="PARAMETER">callbackCommand</REPLACEABLE>
476+
</TERM>
477+
<LISTITEM>
478+
<PARA>If present and not empty, provides the command string to execute
479+
when a matching notification arrives.
480+
</PARA>
481+
</LISTITEM>
482+
</VARLISTENTRY>
483+
</VARIABLELIST>
484+
</REFSECT2>
485+
486+
<REFSECT2 ID="R2-PGTCL-PGLISTEN-2">
487+
<REFSECT2INFO>
488+
<DATE>1998-5-22</DATE>
489+
</REFSECT2INFO>
490+
<TITLE>Outputs
491+
</TITLE>
492+
<VARIABLELIST>
493+
<VARLISTENTRY>
494+
<TERM>
495+
None
496+
</TERM>
497+
<LISTITEM>
498+
<PARA>
499+
</PARA>
500+
</LISTITEM>
501+
</VARLISTENTRY>
502+
</VARIABLELIST>
503+
</REFSECT2>
504+
</REFSYNOPSISDIV>
505+
506+
<REFSECT1 ID="R1-PGTCL-PGLISTEN-1">
507+
<REFSECT1INFO>
508+
<DATE>1998-5-22</DATE>
509+
</REFSECT1INFO>
510+
<TITLE>Description
511+
</TITLE>
512+
<PARA><FUNCTION>pg_listen</FUNCTION> creates, changes, or cancels a request
513+
to listen for asynchronous NOTIFY messages from the
514+
<ProductName>Postgres</ProductName> backend. With a callbackCommand
515+
parameter, the request is established, or the command string of an already
516+
existing request is replaced. With no callbackCommand parameter, a prior
517+
request is canceled.
518+
</PARA>
519+
After a <PARA><FUNCTION>pg_listen</FUNCTION> request is established,
520+
the specified command string is executed whenever a NOTIFY message bearing
521+
the given name arrives from the backend. This occurs when any
522+
<ProductName>Postgres</ProductName> client application issues a NOTIFY command
523+
referencing that name. (Note that the name can be, but does not have to be,
524+
that of an existing relation in the database.)
525+
The command string is executed from the Tcl idle loop. That is the normal
526+
idle state of an application written with Tk. In non-Tk Tcl shells, you can
527+
execute <FUNCTION>update</FUNCTION> or <FUNCTION>vwait</FUNCTION> to cause
528+
the idle loop to be entered.
418529
</PARA>
419530
</REFSECT1>
420531

‎src/interfaces/libpgtcl/pgtcl.c

Lines changed: 3 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
*
1010
*
1111
* IDENTIFICATION
12-
* $Header: /cvsroot/pgsql/src/interfaces/libpgtcl/Attic/pgtcl.c,v 1.10 1998/03/15 08:02:57 scrappy Exp $
12+
* $Header: /cvsroot/pgsql/src/interfaces/libpgtcl/Attic/pgtcl.c,v 1.11 1998/06/16 04:10:15 momjian Exp $
1313
*
1414
*-------------------------------------------------------------------------
1515
*/
@@ -36,7 +36,7 @@ Pgtcl_Init (Tcl_Interp *interp)
3636
* to guess where it might be by position in the struct. This is needed
3737
* for Tcl7.6 and beyond, which have the getfileproc.
3838
*/
39-
#if (TCL_MAJOR_VERSION == 7 && TCL_MINOR_VERSION == 6)
39+
#if HAVE_TCL_GETFILEPROC
4040
Pg_ConnType.getFileProc = PgGetFileProc;
4141
#endif
4242

@@ -126,12 +126,7 @@ Pgtcl_Init (Tcl_Interp *interp)
126126
Pg_listen,
127127
(ClientData)NULL, (Tcl_CmdDeleteProc*)NULL);
128128

129-
Tcl_CreateCommand(interp,
130-
"pg_notifies",
131-
Pg_notifies,
132-
(ClientData)NULL, (Tcl_CmdDeleteProc*)NULL);
133-
134-
Tcl_PkgProvide(interp, "Pgtcl", "1.1");
129+
Tcl_PkgProvide(interp, "Pgtcl", "1.2");
135130

136131
return TCL_OK;
137132
}

0 commit comments

Comments
 (0)