First phase of plan-invalidation project: create a plan cache management

module and teach PREPARE and protocol-level prepared statements to use it.
In service of this, rearrange utility-statement processing so that parse
analysis does not assume table schemas can't change before execution for
utility statements (necessary because we don't attempt to re-acquire locks
for utility statements when reusing a stored plan).  This requires some
refactoring of the ProcessUtility API, but it ends up cleaner anyway,
for instance we can get rid of the QueryContext global.

Still to do: fix up SPI and related code to use the plan cache; I'm tempted to
try to make SQL functions use it too.  Also, there are at least some aspects
of system state that we want to ensure remain the same during a replan as in
the original processing; search_path certainly ought to behave that way for
instance, and perhaps there are others.

4 files changed, 121 insertions, 17 deletions

diff --git a/src/include/utils/memutils.h b/src/include/utils/memutils.h
index fd304b66ad5..f046f397e8c 100644
--- a/src/include/utils/memutils.h
+++ b/src/include/utils/memutils.h
@@ -10,7 +10,7 @@
  * Portions Copyright (c) 1996-2007, PostgreSQL Global Development Group
  * Portions Copyright (c) 1994, Regents of the University of California
  *
- * $PostgreSQL: pgsql/src/include/utils/memutils.h,v 1.61 2007/01/05 22:19:59 momjian Exp $
+ * $PostgreSQL: pgsql/src/include/utils/memutils.h,v 1.62 2007/03/13 00:33:43 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -75,8 +75,7 @@ extern DLLIMPORT MemoryContext MessageContext;
 extern DLLIMPORT MemoryContext TopTransactionContext;
 extern DLLIMPORT MemoryContext CurTransactionContext;
 
-/* These two are transient links to contexts owned by other objects: */
-extern DLLIMPORT MemoryContext QueryContext;
+/* This is a transient link to the active portal's memory context: */
 extern DLLIMPORT MemoryContext PortalContext;
 
 
diff --git a/src/include/utils/plancache.h b/src/include/utils/plancache.h
new file mode 100644
index 00000000000..833ec473b13
--- /dev/null
+++ b/src/include/utils/plancache.h
@@ -0,0 +1,105 @@
+/*-------------------------------------------------------------------------
+ *
+ * plancache.h
+ *	  Plan cache definitions.
+ *
+ * See plancache.c for comments.
+ *
+ * Portions Copyright (c) 1996-2007, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1994, Regents of the University of California
+ *
+ * $PostgreSQL: pgsql/src/include/utils/plancache.h,v 1.1 2007/03/13 00:33:43 tgl Exp $
+ *
+ *-------------------------------------------------------------------------
+ */
+#ifndef PLANCACHE_H
+#define PLANCACHE_H
+
+#include "access/tupdesc.h"
+
+/*
+ * CachedPlanSource represents the portion of a cached plan that persists
+ * across invalidation/replan cycles.  It stores a raw parse tree (required),
+ * the original source text (optional, but highly recommended to improve
+ * error reports), and adjunct data.
+ *
+ * Normally, both the struct itself and the subsidiary data live in the
+ * context denoted by the context field, while the linked-to CachedPlan, if
+ * any, has its own context.  Thus an invalidated CachedPlan can be dropped
+ * when no longer needed, and conversely a CachedPlanSource can be dropped
+ * without worrying whether any portals depend on particular instances of
+ * its plan.
+ *
+ * But for entries created by FastCreateCachedPlan, the CachedPlanSource
+ * and the initial version of the CachedPlan share the same memory context.
+ * In this case, we treat the memory context as belonging to the CachedPlan.
+ * The CachedPlanSource has an extra reference-counted link (orig_plan)
+ * to the CachedPlan, and the memory context goes away when the CachedPlan's
+ * reference count goes to zero.  This arrangement saves overhead for plans
+ * that aren't expected to live long enough to need replanning, while not
+ * losing any flexibility if a replan turns out to be necessary.
+ *
+ * Note: the string referenced by commandTag is not subsidiary storage;
+ * it is assumed to be a compile-time-constant string.  As with portals,
+ * commandTag shall be NULL if and only if the original query string (before
+ * rewriting) was an empty string.
+ */
+typedef struct CachedPlanSource
+{
+	Node	   *raw_parse_tree;	/* output of raw_parser() */
+	char	   *query_string;	/* text of query, or NULL */
+	const char *commandTag;		/* command tag (a constant!), or NULL */
+	Oid		   *param_types;	/* array of parameter type OIDs, or NULL */
+	int			num_params;		/* length of param_types array */
+	bool		fully_planned;	/* do we cache planner or rewriter output? */
+	bool		fixed_result;	/* disallow change in result tupdesc? */
+	int			generation;		/* counter, starting at 1, for replans */
+	TupleDesc	resultDesc;		/* result type; NULL = doesn't return tuples */
+	struct CachedPlan *plan;	/* link to plan, or NULL if not valid */
+	MemoryContext context;		/* context containing this CachedPlanSource */
+	struct CachedPlan *orig_plan;	/* link to plan owning my context */
+} CachedPlanSource;
+
+/*
+ * CachedPlan represents the portion of a cached plan that is discarded when
+ * invalidation occurs.  The reference count includes both the link(s) from the
+ * parent CachedPlanSource, and any active plan executions, so the plan can be
+ * discarded exactly when refcount goes to zero.  Both the struct itself and
+ * the subsidiary data live in the context denoted by the context field.
+ * This makes it easy to free a no-longer-needed cached plan.
+ */
+typedef struct CachedPlan
+{
+	List	   *stmt_list;		/* list of statement or Query nodes */
+	bool		fully_planned;	/* do we cache planner or rewriter output? */
+	bool		dead;			/* if true, do not use */
+	int			refcount;		/* count of live references to this struct */
+	int			generation;		/* counter, starting at 1, for replans */
+	MemoryContext context;		/* context containing this CachedPlan */
+} CachedPlan;
+
+
+extern void InitPlanCache(void);
+extern CachedPlanSource *CreateCachedPlan(Node *raw_parse_tree,
+										  const char *query_string,
+										  const char *commandTag,
+										  Oid *param_types,
+										  int num_params,
+										  List *stmt_list,
+										  bool fully_planned,
+										  bool fixed_result);
+extern CachedPlanSource *FastCreateCachedPlan(Node *raw_parse_tree,
+											  char *query_string,
+											  const char *commandTag,
+											  Oid *param_types,
+											  int num_params,
+											  List *stmt_list,
+											  bool fully_planned,
+											  bool fixed_result,
+											  MemoryContext context);
+extern void DropCachedPlan(CachedPlanSource *plansource);
+extern CachedPlan *RevalidateCachedPlan(CachedPlanSource *plansource,
+										bool useResOwner);
+extern void ReleaseCachedPlan(CachedPlan *plan, bool useResOwner);
+
+#endif   /* PLANCACHE_H */
diff --git a/src/include/utils/portal.h b/src/include/utils/portal.h
index aa432abb876..47651006a21 100644
--- a/src/include/utils/portal.h
+++ b/src/include/utils/portal.h
@@ -39,7 +39,7 @@
  * Portions Copyright (c) 1996-2007, PostgreSQL Global Development Group
  * Portions Copyright (c) 1994, Regents of the University of California
  *
- * $PostgreSQL: pgsql/src/include/utils/portal.h,v 1.73 2007/02/20 17:32:18 tgl Exp $
+ * $PostgreSQL: pgsql/src/include/utils/portal.h,v 1.74 2007/03/13 00:33:43 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -94,7 +94,8 @@ typedef enum PortalStrategy
  */
 typedef enum PortalStatus
 {
-	PORTAL_NEW,					/* in process of creation */
+	PORTAL_NEW,					/* freshly created */
+	PORTAL_DEFINED,				/* PortalDefineQuery done */
 	PORTAL_READY,				/* PortalStart complete, can run it */
 	PORTAL_ACTIVE,				/* portal is running (can't delete it) */
 	PORTAL_DONE,				/* portal is finished (don't re-run it) */
@@ -125,15 +126,7 @@ typedef struct PortalData
 	const char *sourceText;		/* text of query, if known (may be NULL) */
 	const char *commandTag;		/* command tag for original query */
 	List	   *stmts;			/* PlannedStmts and/or utility statements */
-	MemoryContext queryContext; /* where the plan trees live */
-
-	/*
-	 * Note: queryContext effectively identifies which prepared statement the
-	 * portal depends on, if any.  The queryContext is *not* owned by the
-	 * portal and is not to be deleted by portal destruction.  (But for a
-	 * cursor it is the same as "heap", and that context is deleted by portal
-	 * destruction.)  The plan trees may be in either queryContext or heap.
-	 */
+	CachedPlan *cplan;			/* CachedPlan, if stmts are from one */
 
 	ParamListInfo portalParams; /* params to pass to query */
 
@@ -210,14 +203,13 @@ extern void AtSubCleanup_Portals(SubTransactionId mySubid);
 extern Portal CreatePortal(const char *name, bool allowDup, bool dupSilent);
 extern Portal CreateNewPortal(void);
 extern void PortalDrop(Portal portal, bool isTopCommit);
-extern void DropDependentPortals(MemoryContext queryContext);
 extern Portal GetPortalByName(const char *name);
 extern void PortalDefineQuery(Portal portal,
 				  const char *prepStmtName,
 				  const char *sourceText,
 				  const char *commandTag,
 				  List *stmts,
-				  MemoryContext queryContext);
+				  CachedPlan *cplan);
 extern Node *PortalListGetPrimaryStmt(List *stmts);
 extern void PortalCreateHoldStore(Portal portal);
 
diff --git a/src/include/utils/resowner.h b/src/include/utils/resowner.h
index 663096a333f..ea0d6a74066 100644
--- a/src/include/utils/resowner.h
+++ b/src/include/utils/resowner.h
@@ -12,7 +12,7 @@
  * Portions Copyright (c) 1996-2007, PostgreSQL Global Development Group
  * Portions Copyright (c) 1994, Regents of the University of California
  *
- * $PostgreSQL: pgsql/src/include/utils/resowner.h,v 1.10 2007/01/05 22:19:59 momjian Exp $
+ * $PostgreSQL: pgsql/src/include/utils/resowner.h,v 1.11 2007/03/13 00:33:43 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -21,6 +21,7 @@
 
 #include "storage/buf.h"
 #include "utils/catcache.h"
+#include "utils/plancache.h"
 
 
 /*
@@ -106,6 +107,13 @@ extern void ResourceOwnerRememberRelationRef(ResourceOwner owner,
 extern void ResourceOwnerForgetRelationRef(ResourceOwner owner,
 							   Relation rel);
 
+/* support for plancache refcount management */
+extern void ResourceOwnerEnlargePlanCacheRefs(ResourceOwner owner);
+extern void ResourceOwnerRememberPlanCacheRef(ResourceOwner owner,
+											  CachedPlan *plan);
+extern void ResourceOwnerForgetPlanCacheRef(ResourceOwner owner,
+											CachedPlan *plan);
+
 /* support for tupledesc refcount management */
 extern void ResourceOwnerEnlargeTupleDescs(ResourceOwner owner);
 extern void ResourceOwnerRememberTupleDesc(ResourceOwner owner,