Add an "events" system to libpq, whereby applications can get callbacks that

enable them to manage private data associated with PGconns and PGresults.

Andrew Chernow and Merlin Moncure

src/interfaces/libpq/Makefile

@@ -5,7 +5,7 @@
 # Portions Copyright (c) 1996-2008, PostgreSQL Global Development Group
 # Portions Copyright (c) 1994, Regents of the University of California
 #
-# $PostgreSQL: pgsql/src/interfaces/libpq/Makefile,v 1.166 2008/04/16 14:19:56 adunstan Exp $
+# $PostgreSQL: pgsql/src/interfaces/libpq/Makefile,v 1.167 2008/09/17 04:31:08 tgl Exp $
 #
 #-------------------------------------------------------------------------
 
@@ -32,6 +32,7 @@ LIBS := $(LIBS:-lpgport=)
 
 OBJS=	fe-auth.o fe-connect.o fe-exec.o fe-misc.o fe-print.o fe-lobj.o \
 	fe-protocol2.o fe-protocol3.o pqexpbuffer.o pqsignal.o fe-secure.o \
+	libpq-events.o \
 	md5.o ip.o wchar.o encnames.o noblock.o pgstrcasecmp.o thread.o \
 	$(filter crypt.o getaddrinfo.o inet_aton.o open.o snprintf.o strerror.o strlcpy.o win32error.o, $(LIBOBJS))
 
@@ -106,6 +107,7 @@ $(top_builddir)/src/port/pg_config_paths.h:
 
 install: all installdirs install-lib
 	$(INSTALL_DATA) $(srcdir)/libpq-fe.h '$(DESTDIR)$(includedir)'
+	$(INSTALL_DATA) $(srcdir)/libpq-events.h '$(DESTDIR)$(includedir)'
 	$(INSTALL_DATA) $(srcdir)/libpq-int.h '$(DESTDIR)$(includedir_internal)'
 	$(INSTALL_DATA) $(srcdir)/pqexpbuffer.h '$(DESTDIR)$(includedir_internal)'
 	$(INSTALL_DATA) $(srcdir)/pg_service.conf.sample '$(DESTDIR)$(datadir)/pg_service.conf.sample'
@@ -114,7 +116,11 @@ installdirs: installdirs-lib
 	$(mkinstalldirs) '$(DESTDIR)$(includedir)' '$(DESTDIR)$(includedir_internal)'
 
 uninstall: uninstall-lib
-	rm -f '$(DESTDIR)$(includedir)/libpq-fe.h' '$(DESTDIR)$(includedir_internal)/libpq-int.h' '$(DESTDIR)$(includedir_internal)/pqexpbuffer.h' '$(DESTDIR)$(datadir)/pg_service.conf.sample'
+	rm -f '$(DESTDIR)$(includedir)/libpq-fe.h'
+	rm -f '$(DESTDIR)$(includedir)/libpq-events.h'
+	rm -f '$(DESTDIR)$(includedir_internal)/libpq-int.h'
+	rm -f '$(DESTDIR)$(includedir_internal)/pqexpbuffer.h'
+	rm -f '$(DESTDIR)$(datadir)/pg_service.conf.sample'
 
 clean distclean: clean-lib
 	rm -f $(OBJS) pg_config_paths.h crypt.c getaddrinfo.c inet_aton.c noblock.c open.c pgstrcasecmp.c snprintf.c strerror.c strlcpy.c thread.c md5.c ip.c encnames.c wchar.c win32error.c pgsleep.c pthread.h libpq.rc

src/interfaces/libpq/exports.txt

-# $PostgreSQL: pgsql/src/interfaces/libpq/exports.txt,v 1.19 2008/03/19 00:39:33 ishii Exp $
+# $PostgreSQL: pgsql/src/interfaces/libpq/exports.txt,v 1.20 2008/09/17 04:31:08 tgl Exp $
 # Functions to be exported by libpq DLLs
 PQconnectdb               1
 PQsetdbLogin              2
@@ -140,4 +140,13 @@ lo_truncate               137
 PQconnectionUsedPassword  138
 pg_valid_server_encoding_id 139
 PQconnectionNeedsPassword 140
-lo_import_with_oid		  141
+lo_import_with_oid        141
+PQcopyResult              142
+PQsetResultAttrs          143
+PQsetvalue                144
+PQresultAlloc             145
+PQregisterEventProc       146
+PQinstanceData            147
+PQsetInstanceData         148
+PQresultInstanceData      149
+PQresultSetInstanceData   150

src/interfaces/libpq/fe-connect.c

@@ -8,7 +8,7 @@
  *
  *
  * IDENTIFICATION
- *	  $PostgreSQL: pgsql/src/interfaces/libpq/fe-connect.c,v 1.359 2008/05/29 22:02:44 tgl Exp $
+ *	  $PostgreSQL: pgsql/src/interfaces/libpq/fe-connect.c,v 1.360 2008/09/17 04:31:08 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -1974,6 +1974,21 @@ makeEmptyPGconn(void)
 static void
 freePGconn(PGconn *conn)
 {
+	int			i;
+
+	/* let any event procs clean up their state data */
+	for (i = 0; i < conn->nEvents; i++)
+	{
+		PGEventConnDestroy evt;
+
+		evt.conn = conn;
+		(void) conn->events[i].proc(PGEVT_CONNDESTROY, &evt,
+									conn->events[i].passThrough);
+		free(conn->events[i].name);
+	}
+
+	if (conn->events)
+		free(conn->events);
 	if (conn->pghost)
 		free(conn->pghost);
 	if (conn->pghostaddr)
@@ -2155,8 +2170,30 @@ PQreset(PGconn *conn)
 	{
 		closePGconn(conn);
 
-		if (connectDBStart(conn))
-			(void) connectDBComplete(conn);
+		if (connectDBStart(conn) && connectDBComplete(conn))
+		{
+			/*
+			 * Notify event procs of successful reset.  We treat an event
+			 * proc failure as disabling the connection ... good idea?
+			 */
+			int i;
+
+			for (i = 0; i < conn->nEvents; i++)
+			{
+				PGEventConnReset evt;
+
+				evt.conn = conn;
+				if (!conn->events[i].proc(PGEVT_CONNRESET, &evt,
+										  conn->events[i].passThrough))
+				{
+					conn->status = CONNECTION_BAD;
+					printfPQExpBuffer(&conn->errorMessage,
+									  libpq_gettext("PGEventProc \"%s\" failed during PGEVT_CONNRESET event\n"),
+									  conn->events[i].name);
+					break;
+				}
+			}
+		}
 	}
 }
 
@@ -2190,7 +2227,36 @@ PostgresPollingStatusType
 PQresetPoll(PGconn *conn)
 {
 	if (conn)
-		return PQconnectPoll(conn);
+	{
+		PostgresPollingStatusType status = PQconnectPoll(conn);
+
+		if (status == PGRES_POLLING_OK)
+		{
+			/*
+			 * Notify event procs of successful reset.  We treat an event
+			 * proc failure as disabling the connection ... good idea?
+			 */
+			int i;
+
+			for (i = 0; i < conn->nEvents; i++)
+			{
+				PGEventConnReset evt;
+
+				evt.conn = conn;
+				if (!conn->events[i].proc(PGEVT_CONNRESET, &evt,
+										  conn->events[i].passThrough))
+				{
+					conn->status = CONNECTION_BAD;
+					printfPQExpBuffer(&conn->errorMessage,
+									  libpq_gettext("PGEventProc \"%s\" failed during PGEVT_CONNRESET event\n"),
+									  conn->events[i].name);
+					return PGRES_POLLING_FAILED;
+				}
+			}
+		}
+
+		return status;
+	}
 
 	return PGRES_POLLING_FAILED;
 }

src/interfaces/libpq/libpq-events.c

+/*-------------------------------------------------------------------------
+ *
+ * libpq-events.c
+ *	  functions for supporting the libpq "events" API
+ *
+ * Portions Copyright (c) 1996-2008, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1994, Regents of the University of California
+ *
+ *
+ * IDENTIFICATION
+ *	  $PostgreSQL: pgsql/src/interfaces/libpq/libpq-events.c,v 1.1 2008/09/17 04:31:08 tgl Exp $
+ *
+ *-------------------------------------------------------------------------
+ */
+#include "postgres_fe.h"
+
+#include "libpq-fe.h"
+#include "libpq-int.h"
+
+
+/*
+ * Registers an event proc with the given PGconn.
+ *
+ * The same proc can't be registered more than once in a PGconn.  This
+ * restriction is required because we use the proc address to identify
+ * the event for purposes such as PQinstanceData().
+ *
+ * The name argument is used within error messages to aid in debugging.
+ * A name must be supplied, but it needn't be unique.  The string is
+ * copied, so the passed value needn't be long-lived.
+ *
+ * The passThrough argument is an application specific pointer and can be set
+ * to NULL if not required.  It is passed through to the event proc whenever
+ * the event proc is called, and is not otherwise touched by libpq.
+ *
+ * The function returns a non-zero if successful.  If the function fails,
+ * zero is returned.
+ */
+int
+PQregisterEventProc(PGconn *conn, PGEventProc proc,
+					const char *name, void *passThrough)
+{
+	int i;
+	PGEventRegister regevt;
+
+	if (!proc || !conn || !name || !*name)
+		return FALSE;			/* bad arguments */
+
+	for (i = 0; i < conn->nEvents; i++)
+	{
+		if (conn->events[i].proc == proc)
+			return FALSE;		/* already registered */
+	}
+
+	if (conn->nEvents >= conn->eventArraySize)
+	{
+		PGEvent *e;
+		int newSize;
+
+		newSize = conn->eventArraySize ? conn->eventArraySize * 2 : 8;
+		if (conn->events)
+			e = (PGEvent *) realloc(conn->events, newSize * sizeof(PGEvent));
+		else
+			e = (PGEvent *) malloc(newSize * sizeof(PGEvent));
+
+		if (!e)
+			return FALSE;
+
+		conn->eventArraySize = newSize;
+		conn->events = e;
+	}
+
+	conn->events[conn->nEvents].proc = proc;
+	conn->events[conn->nEvents].name = strdup(name);
+	if (!conn->events[conn->nEvents].name)
+		return FALSE;
+	conn->events[conn->nEvents].passThrough = passThrough;
+	conn->events[conn->nEvents].data = NULL;
+	conn->nEvents++;
+
+	regevt.conn = conn;
+	if (!proc(PGEVT_REGISTER, &regevt, passThrough))
+	{
+		conn->nEvents--;
+		free(conn->events[conn->nEvents].name);
+		return FALSE;
+	}
+
+	return TRUE;
+}
+
+/*
+ * Set some "instance data" for an event within a PGconn.
+ * Returns nonzero on success, zero on failure.
+ */
+int
+PQsetInstanceData(PGconn *conn, PGEventProc proc, void *data)
+{
+	int i;
+
+	if (!conn || !proc)
+		return FALSE;
+
+	for (i = 0; i < conn->nEvents; i++)
+	{
+		if (conn->events[i].proc == proc)
+		{
+			conn->events[i].data = data;
+			return TRUE;
+		}
+	}
+
+	return FALSE;
+}
+
+/*
+ * Obtain the "instance data", if any, for the event.
+ */
+void *
+PQinstanceData(const PGconn *conn, PGEventProc proc)
+{
+	int i;
+
+	if (!conn || !proc)
+		return NULL;
+
+	for (i = 0; i < conn->nEvents; i++)
+	{
+		if (conn->events[i].proc == proc)
+			return conn->events[i].data;
+	}
+
+	return NULL;
+}
+
+/*
+ * Set some "instance data" for an event within a PGresult.
+ * Returns nonzero on success, zero on failure.
+ */
+int
+PQresultSetInstanceData(PGresult *result, PGEventProc proc, void *data)
+{
+	int i;
+
+	if (!result || !proc)
+		return FALSE;
+
+	for (i = 0; i < result->nEvents; i++)
+	{
+		if (result->events[i].proc == proc)
+		{
+			result->events[i].data = data;
+			return TRUE;
+		}
+	}
+
+	return FALSE;
+}
+
+/*
+ * Obtain the "instance data", if any, for the event.
+ */
+void *
+PQresultInstanceData(const PGresult *result, PGEventProc proc)
+{
+	int i;
+
+	if (!result || !proc)
+		return NULL;
+
+	for (i = 0; i < result->nEvents; i++)
+		if (result->events[i].proc == proc)
+			return result->events[i].data;
+
+	return NULL;
+}

src/interfaces/libpq/libpq-events.h

+/*-------------------------------------------------------------------------
+ *
+ * libpq-events.h
+ *	  This file contains definitions that are useful to applications
+ *	  that invoke the libpq "events" API, but are not interesting to
+ *	  ordinary users of libpq.
+ *
+ * Portions Copyright (c) 1996-2008, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1994, Regents of the University of California
+ *
+ * $PostgreSQL: pgsql/src/interfaces/libpq/libpq-events.h,v 1.1 2008/09/17 04:31:08 tgl Exp $
+ *
+ *-------------------------------------------------------------------------
+ */
+
+#ifndef LIBPQ_EVENTS_H
+#define LIBPQ_EVENTS_H
+
+#include "libpq-fe.h"
+
+#ifdef __cplusplus
+extern		"C"
+{
+#endif
+
+/* Callback Event Ids */
+typedef enum
+{
+	PGEVT_REGISTER,
+	PGEVT_CONNRESET,
+	PGEVT_CONNDESTROY,
+	PGEVT_RESULTCREATE,
+	PGEVT_RESULTCOPY,
+	PGEVT_RESULTDESTROY
+} PGEventId;
+
+typedef struct
+{
+	const PGconn *conn;
+} PGEventRegister;
+
+typedef struct
+{
+	const PGconn *conn;
+} PGEventConnReset;
+
+typedef struct
+{
+	const PGconn *conn;
+} PGEventConnDestroy;
+
+typedef struct
+{
+	const PGconn *conn;
+	PGresult *result;
+} PGEventResultCreate;
+
+typedef struct
+{
+	const PGresult *src;
+	PGresult *dest;
+} PGEventResultCopy;
+
+typedef struct
+{
+	const PGresult *result;
+} PGEventResultDestroy;
+
+typedef int (*PGEventProc) (PGEventId evtId, void *evtInfo, void *passThrough);
+
+/* Registers an event proc with the given PGconn. */
+extern int	PQregisterEventProc(PGconn *conn, PGEventProc proc,
+								const char *name, void *passThrough);
+
+/* Sets the PGconn instance data for the provided proc to data. */
+extern int	PQsetInstanceData(PGconn *conn, PGEventProc proc, void *data);
+
+/* Gets the PGconn instance data for the provided proc. */
+extern void *PQinstanceData(const PGconn *conn, PGEventProc proc);
+
+/* Sets the PGresult instance data for the provided proc to data. */
+extern int	PQresultSetInstanceData(PGresult *result, PGEventProc proc, void *data);
+
+/* Gets the PGresult instance data for the provided proc. */
+extern void *PQresultInstanceData(const PGresult *result, PGEventProc proc);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* LIBPQ_EVENTS_H */

src/interfaces/libpq/libpq-fe.h

@@ -7,7 +7,7 @@
  * Portions Copyright (c) 1996-2008, PostgreSQL Global Development Group
  * Portions Copyright (c) 1994, Regents of the University of California
  *
- * $PostgreSQL: pgsql/src/interfaces/libpq/libpq-fe.h,v 1.142 2008/03/19 00:39:33 ishii Exp $
+ * $PostgreSQL: pgsql/src/interfaces/libpq/libpq-fe.h,v 1.143 2008/09/17 04:31:08 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -28,6 +28,14 @@ extern		"C"
  */
 #include "postgres_ext.h"
 
+/*
+ * Option flags for PQcopyResult
+ */
+#define PG_COPYRES_ATTRS          0x01
+#define PG_COPYRES_TUPLES         0x02		/* Implies PG_COPYRES_ATTRS */
+#define PG_COPYRES_EVENTS         0x04
+#define PG_COPYRES_NOTICEHOOKS    0x08
+
 /* Application-visible enum types */
 
 typedef enum
@@ -192,6 +200,21 @@ typedef struct
 	}			u;
 } PQArgBlock;
 
+/* ----------------
+ * PGresAttDesc -- Data about a single attribute (column) of a query result
+ * ----------------
+ */
+typedef struct pgresAttDesc
+{
+	char	   *name;			/* column name */
+	Oid			tableid;		/* source table, if known */
+	int			columnid;		/* source column, if known */
+	int			format;			/* format code for value (text/binary) */
+	Oid			typid;			/* type id */
+	int			typlen;			/* type size */
+	int			atttypmod;		/* type-specific modifier info */
+} PGresAttDesc;
+
 /* ----------------
  * Exported functions of libpq
  * ----------------
@@ -430,13 +453,12 @@ extern void PQfreemem(void *ptr);
 /* Note: depending on this is deprecated; use PQconnectionNeedsPassword(). */
 #define PQnoPasswordSupplied	"fe_sendauth: no password supplied\n"
 
-/*
- * Make an empty PGresult with given status (some apps find this
- * useful). If conn is not NULL and status indicates an error, the
- * conn's errorMessage is copied.
- */
+/* Create and manipulate PGresults */
 extern PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
-
+extern PGresult *PQcopyResult(const PGresult *src, int flags);
+extern int PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs);
+extern void *PQresultAlloc(PGresult *res, size_t nBytes);
+extern int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len);
 
 /* Quoting strings before inclusion in queries. */
 extern size_t PQescapeStringConn(PGconn *conn,

src/interfaces/libpq/libpq-int.h

@@ -12,7 +12,7 @@
  * Portions Copyright (c) 1996-2008, PostgreSQL Global Development Group
  * Portions Copyright (c) 1994, Regents of the University of California
  *
- * $PostgreSQL: pgsql/src/interfaces/libpq/libpq-int.h,v 1.131 2008/05/29 22:02:44 tgl Exp $
+ * $PostgreSQL: pgsql/src/interfaces/libpq/libpq-int.h,v 1.132 2008/09/17 04:31:08 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -22,6 +22,7 @@
 
 /* We assume libpq-fe.h has already been included. */
 #include "postgres_fe.h"
+#include "libpq-events.h"
 
 #include <time.h>
 #include <sys/types.h>
@@ -100,19 +101,6 @@ union pgresult_data
 	char		space[1];		/* dummy for accessing block as bytes */
 };
 
-/* Data about a single attribute (column) of a query result */
-
-typedef struct pgresAttDesc
-{
-	char	   *name;			/* column name */
-	Oid			tableid;		/* source table, if known */
-	int			columnid;		/* source column, if known */
-	int			format;			/* format code for value (text/binary) */
-	Oid			typid;			/* type id */
-	int			typlen;			/* type size */
-	int			atttypmod;		/* type-specific modifier info */
-} PGresAttDesc;
-
 /* Data about a single parameter of a prepared statement */
 typedef struct pgresParamDesc
 {
@@ -162,6 +150,14 @@ typedef struct
 	void	   *noticeProcArg;
 } PGNoticeHooks;
 
+typedef struct PGEvent
+{
+	PGEventProc	proc;			/* the function to call on events */
+	char	   *name;			/* used only for error messages */
+	void	   *passThrough;	/* pointer supplied at registration time */
+	void	   *data;			/* optional state (instance) data */
+} PGEvent;
+
 struct pg_result
 {
 	int			ntups;
@@ -182,6 +178,8 @@ struct pg_result
 	 * on the PGresult don't have to reference the PGconn.
 	 */
 	PGNoticeHooks noticeHooks;
+	PGEvent	   *events;
+	int			nEvents;
 	int			client_encoding;	/* encoding id */
 
 	/*
@@ -303,6 +301,11 @@ struct pg_conn
 	/* Callback procedures for notice message processing */
 	PGNoticeHooks noticeHooks;
 
+	/* Event procs registered via PQregisterEventProc */
+	PGEvent	   *events;			/* expandable array of event data */
+	int			nEvents;		/* number of active events */
+	int			eventArraySize;	/* allocated array size */
+
 	/* Status indicators */
 	ConnStatusType status;
 	PGAsyncStatusType asyncStatus;

src/tools/msvc/Install.pm

@@ -3,7 +3,7 @@ package Install;
 #
 # Package that provides 'make install' functionality for msvc builds
 #
-# $PostgreSQL: pgsql/src/tools/msvc/Install.pm,v 1.30 2008/09/05 16:54:39 momjian Exp $
+# $PostgreSQL: pgsql/src/tools/msvc/Install.pm,v 1.31 2008/09/17 04:31:08 tgl Exp $
 #
 use strict;
 use warnings;
@@ -393,7 +393,9 @@ sub CopyIncludeFiles
     lcopy('src/include/libpq/libpq-fs.h', $target . '/include/libpq/')
       || croak 'Could not copy libpq-fs.h';
 
-    CopyFiles('Libpq headers', $target . '/include/', 'src/interfaces/libpq/', 'libpq-fe.h');
+    CopyFiles('Libpq headers',
+	      $target . '/include/', 'src/interfaces/libpq/',
+	      'libpq-fe.h', 'libpq-events.h');
     CopyFiles(
         'Libpq internal headers',
         $target .'/include/internal/',