From 54f7338fa119802cabb12f7fc0020a167d9690c0 Mon Sep 17 00:00:00 2001
From: Bruce Momjian <bruce@momjian.us>
Date: Thu, 27 Mar 2003 16:51:29 +0000
Subject: This patch implements holdable cursors, following the proposal
 (materialization into a tuple store) discussed on pgsql-hackers earlier. I've
 updated the documentation and the regression tests.

Notes on the implementation:

- I needed to change the tuple store API slightly -- it assumes that it
won't be used to hold data across transaction boundaries, so the temp
files that it uses for on-disk storage are automatically reclaimed at
end-of-transaction. I added a flag to tuplestore_begin_heap() to control
this behavior. Is changing the tuple store API in this fashion OK?

- in order to store executor results in a tuple store, I added a new
CommandDest. This works well for the most part, with one exception: the
current DestFunction API doesn't provide enough information to allow the
Executor to store results into an arbitrary tuple store (where the
particular tuple store to use is chosen by the call site of
ExecutorRun). To workaround this, I've temporarily hacked up a solution
that works, but is not ideal: since the receiveTuple DestFunction is
passed the portal name, we can use that to lookup the Portal data
structure for the cursor and then use that to get at the tuple store the
Portal is using. This unnecessarily ties the Portal code with the
tupleReceiver code, but it works...

The proper fix for this is probably to change the DestFunction API --
Tom suggested passing the full QueryDesc to the receiveTuple function.
In that case, callers of ExecutorRun could "subclass" QueryDesc to add
any additional fields that their particular CommandDest needed to get
access to. This approach would work, but I'd like to think about it for
a little bit longer before deciding which route to go. In the mean time,
the code works fine, so I don't think a fix is urgent.

- (semi-related) I added a NO SCROLL keyword to DECLARE CURSOR, and
adjusted the behavior of SCROLL in accordance with the discussion on
-hackers.

- (unrelated) Cleaned up some SGML markup in sql.sgml, copy.sgml

Neil Conway
---
 src/include/utils/portal.h | 39 ++++++++++++++++++++++++++++++++++-----
 1 file changed, 34 insertions(+), 5 deletions(-)

(limited to 'src/include/utils/portal.h')

diff --git a/src/include/utils/portal.h b/src/include/utils/portal.h
index c9ca8547ce2..0201b0684c3 100644
--- a/src/include/utils/portal.h
+++ b/src/include/utils/portal.h
@@ -9,7 +9,7 @@
  * Portions Copyright (c) 1996-2002, PostgreSQL Global Development Group
  * Portions Copyright (c) 1994, Regents of the University of California
  *
- * $Id: portal.h,v 1.39 2003/03/11 19:40:24 tgl Exp $
+ * $Id: portal.h,v 1.40 2003/03/27 16:51:29 momjian Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -18,17 +18,45 @@
 
 #include "executor/execdesc.h"
 #include "nodes/memnodes.h"
+#include "utils/tuplestore.h"
 
+/*
+ * We support three kinds of scroll behavior:
+ *
+ * (1) Neither NO SCROLL nor SCROLL was specified: to remain backward
+ *     compatible, we allow backward fetches here, unless it would
+ *     impose additional runtime overhead to do so.
+ *
+ * (2) NO SCROLL was specified: don't allow any backward fetches.
+ *
+ * (3) SCROLL was specified: allow all kinds of backward fetches, even
+ *     if we need to take a slight performance hit to do so.
+ *
+ * Case #1 is converted to #2 or #3 by looking at the query itself and
+ * determining if scrollability can be supported without additional
+ * overhead.
+ */
+typedef enum
+{
+	DEFAULT_SCROLL,
+	DISABLE_SCROLL,
+	ENABLE_SCROLL
+} ScrollType;
 
 typedef struct PortalData *Portal;
 
 typedef struct PortalData
 {
 	char	   *name;			/* Portal's name */
-	MemoryContext heap;			/* subsidiary memory */
+	MemoryContext heap;			/* memory for storing short-term data */
 	QueryDesc  *queryDesc;		/* Info about query associated with portal */
 	void		(*cleanup) (Portal);	/* Cleanup routine (optional) */
-	bool		backwardOK;		/* is fetch backwards allowed? */
+	ScrollType	scrollType;		/* Allow backward fetches? */
+	bool		holdOpen;		/* hold open after txn ends? */
+	TransactionId createXact;	/* the xid of the creating txn */
+	Tuplestorestate *holdStore;	/* store for holdable cursors */
+	MemoryContext holdContext;  /* memory for long-term data */
+
 	/*
 	 * atStart, atEnd and portalPos indicate the current cursor position.
 	 * portalPos is zero before the first row, N after fetching N'th row of
@@ -58,11 +86,12 @@ typedef struct PortalData
 
 
 extern void EnablePortalManager(void);
-extern void AtEOXact_portals(void);
+extern void AtEOXact_portals(bool isCommit);
 extern Portal CreatePortal(const char *name);
-extern void PortalDrop(Portal portal);
+extern void PortalDrop(Portal portal, bool persistHoldable);
 extern Portal GetPortalByName(const char *name);
 extern void PortalSetQuery(Portal portal, QueryDesc *queryDesc,
 						   void (*cleanup) (Portal portal));
+extern void PersistHoldablePortal(Portal portal);
 
 #endif   /* PORTAL_H */
-- 
cgit v1.2.3