/*-------------------------------------------------------------------------

 *

 * plancache.c

 *    Plan cache management.

 *

 * The plan cache manager has two principal responsibilities: deciding when

 * to use a generic plan versus a custom (parameter-value-specific) plan,

 * and tracking whether cached plans need to be invalidated because of schema

 * changes in the objects they depend on.

 *

 * The logic for choosing generic or custom plans is in choose_custom_plan,

 * which see for comments.

 *

 * Cache invalidation is driven off sinval events.  Any CachedPlanSource

 * that matches the event is marked invalid, as is its generic CachedPlan

 * if it has one.  When (and if) the next demand for a cached plan occurs,

 * parse analysis and/or rewrite is repeated to build a new valid query tree,

 * and then planning is performed as normal.  We also force re-analysis and

 * re-planning if the active search_path is different from the previous time

 * or, if RLS is involved, if the user changes or the RLS environment changes.

 *

 * Note that if the sinval was a result of user DDL actions, parse analysis

 * could throw an error, for example if a column referenced by the query is

 * no longer present.  Another possibility is for the query's output tupdesc

 * to change (for instance "SELECT *" might expand differently than before).

 * The creator of a cached plan can specify whether it is allowable for the

 * query to change output tupdesc on replan --- if so, it's up to the

 * caller to notice changes and cope with them.

 *

 * Currently, we track exactly the dependencies of plans on relations,

 * user-defined functions, and domains.  On relcache invalidation events or

 * pg_proc or pg_type syscache invalidation events, we invalidate just those

 * plans that depend on the particular object being modified.  (Note: this

 * scheme assumes that any table modification that requires replanning will

 * generate a relcache inval event.)  We also watch for inval events on

 * certain other system catalogs, such as pg_namespace; but for them, our

 * response is just to invalidate all plans.  We expect updates on those

 * catalogs to be infrequent enough that more-detailed tracking is not worth

 * the effort.  We likewise watch pg_authid, pg_auth_members, and

 * pg_database, which can change which row-level security policies apply.

 * Since those are shared catalogs whose inval events reach every backend

 * in the cluster, we invalidate only the role-dependent plans.

 *

 * In addition to full-fledged query plans, we provide a facility for

 * detecting invalidations of simple scalar expressions.  This is fairly

 * bare-bones; it's the caller's responsibility to build a new expression

 * if the old one gets invalidated.

 *

 *

 * Portions Copyright (c) 1996-2026, PostgreSQL Global Development Group

 * Portions Copyright (c) 1994, Regents of the University of California

 *

 * IDENTIFICATION

 *    src/backend/utils/cache/plancache.c

 *

 *-------------------------------------------------------------------------

 */

#include "postgres.h"

#include <limits.h>

#include "access/transam.h"

#include "catalog/namespace.h"

#include "executor/executor.h"

#include "miscadmin.h"

#include "nodes/nodeFuncs.h"

#include "optimizer/optimizer.h"

#include "parser/analyze.h"

#include "rewrite/rewriteHandler.h"

#include "storage/lmgr.h"

#include "tcop/pquery.h"

#include "tcop/utility.h"

#include "utils/acl.h"

#include "utils/inval.h"

#include "utils/memutils.h"

#include "utils/resowner.h"

#include "utils/rls.h"

#include "utils/snapmgr.h"

#include "utils/syscache.h"

/*

 * This is the head of the backend's list of "saved" CachedPlanSources (i.e.,

 * those that are in long-lived storage and are examined for sinval events).

 * We use a dlist instead of separate List cells so that we can guarantee

 * to save a CachedPlanSource without error.

 */

static dlist_head saved_plan_list = DLIST_STATIC_INIT(saved_plan_list);

/*

 * This is the head of the backend's list of CachedExpressions.

 */

static dlist_head cached_expression_list = DLIST_STATIC_INIT(cached_expression_list);

static void ReleaseGenericPlan(CachedPlanSource *plansource);

static bool StmtPlanRequiresRevalidation(CachedPlanSource *plansource);

static bool BuildingPlanRequiresSnapshot(CachedPlanSource *plansource);

static List *RevalidateCachedQuery(CachedPlanSource *plansource,

                   QueryEnvironment *queryEnv);

static bool CheckCachedPlan(CachedPlanSource *plansource);

static CachedPlan *BuildCachedPlan(CachedPlanSource *plansource, List *qlist,

                   ParamListInfo boundParams, QueryEnvironment *queryEnv);

static bool choose_custom_plan(CachedPlanSource *plansource,

                 ParamListInfo boundParams);

static double cached_plan_cost(CachedPlan *plan, bool include_planner);

static Query *QueryListGetPrimaryStmt(List *stmts);

static void AcquireExecutorLocks(List *stmt_list, bool acquire);

static void AcquirePlannerLocks(List *stmt_list, bool acquire);

static void ScanQueryForLocks(Query *parsetree, bool acquire);

static bool ScanQueryWalker(Node *node, bool *acquire);

static TupleDesc PlanCacheComputeResultDesc(List *stmt_list);

static void PlanCacheRelCallback(Datum arg, Oid relid);

static void PlanCacheObjectCallback(Datum arg, SysCacheIdentifier cacheid,

                  uint32 hashvalue);

static void PlanCacheRoleCallback(Datum arg, SysCacheIdentifier cacheid,

                  uint32 hashvalue);

static void PlanCacheSysCallback(Datum arg, SysCacheIdentifier cacheid,

                 uint32 hashvalue);

/* ResourceOwner callbacks to track plancache references */

static void ResOwnerReleaseCachedPlan(Datum res);

static const ResourceOwnerDesc planref_resowner_desc =

{

  .name = "plancache reference",

  .release_phase = RESOURCE_RELEASE_AFTER_LOCKS,

  .release_priority = RELEASE_PRIO_PLANCACHE_REFS,

  .ReleaseResource = ResOwnerReleaseCachedPlan,

  .DebugPrint = NULL      /* the default message is fine */

};

/* Convenience wrappers over ResourceOwnerRemember/Forget */

static inline void

ResourceOwnerRememberPlanCacheRef(ResourceOwner owner, CachedPlan *plan)

{

  ResourceOwnerRemember(owner, PointerGetDatum(plan), &planref_resowner_desc);

}

static inline void

ResourceOwnerForgetPlanCacheRef(ResourceOwner owner, CachedPlan *plan)

{

  ResourceOwnerForget(owner, PointerGetDatum(plan), &planref_resowner_desc);

}

/* GUC parameter */

int     plan_cache_mode = PLAN_CACHE_MODE_AUTO;

/*

 * InitPlanCache: initialize module during InitPostgres.

 *

 * All we need to do is hook into inval.c's callback lists.

 */

void

InitPlanCache(void)

{

  CacheRegisterRelcacheCallback(PlanCacheRelCallback, (Datum) 0);

  CacheRegisterSyscacheCallback(PROCOID, PlanCacheObjectCallback, (Datum) 0);

  CacheRegisterSyscacheCallback(TYPEOID, PlanCacheObjectCallback, (Datum) 0);

  CacheRegisterSyscacheCallback(NAMESPACEOID, PlanCacheSysCallback, (Datum) 0);

  CacheRegisterSyscacheCallback(OPEROID, PlanCacheSysCallback, (Datum) 0);

  CacheRegisterSyscacheCallback(AMOPOPID, PlanCacheSysCallback, (Datum) 0);

  CacheRegisterSyscacheCallback(FOREIGNSERVEROID, PlanCacheSysCallback, (Datum) 0);

  CacheRegisterSyscacheCallback(FOREIGNDATAWRAPPEROID, PlanCacheSysCallback, (Datum) 0);

  CacheRegisterSyscacheCallback(AUTHMEMROLEMEM, PlanCacheRoleCallback, (Datum) 0);

  CacheRegisterSyscacheCallback(AUTHOID, PlanCacheRoleCallback, (Datum) 0);

  CacheRegisterSyscacheCallback(DATABASEOID, PlanCacheRoleCallback, (Datum) 0);

}

/*

 * CreateCachedPlan: initially create a plan cache entry for a raw parse tree.

 *

 * Creation of a cached plan is divided into two steps, CreateCachedPlan and

 * CompleteCachedPlan.  CreateCachedPlan should be called after running the

 * query through raw_parser, but before doing parse analysis and rewrite;

 * CompleteCachedPlan is called after that.  The reason for this arrangement

 * is that it can save one round of copying of the raw parse tree, since

 * the parser will normally scribble on the raw parse tree.  Callers would

 * otherwise need to make an extra copy of the parse tree to ensure they

 * still had a clean copy to present at plan cache creation time.

 *

 * All arguments presented to CreateCachedPlan are copied into a memory

 * context created as a child of the call-time CurrentMemoryContext, which

 * should be a reasonably short-lived working context that will go away in

 * event of an error.  This ensures that the cached plan data structure will

 * likewise disappear if an error occurs before we have fully constructed it.

 * Once constructed, the cached plan can be made longer-lived, if needed,

 * by calling SaveCachedPlan.

 *

 * raw_parse_tree: output of raw_parser(), or NULL if empty query

 * query_string: original query text

 * commandTag: command tag for query, or UNKNOWN if empty query

 */

CachedPlanSource *

CreateCachedPlan(const RawStmt *raw_parse_tree,

         const char *query_string,

         CommandTag commandTag)

{

  CachedPlanSource *plansource;

  MemoryContext source_context;

  MemoryContext oldcxt;

  Assert(query_string != NULL); /* required as of 8.4 */

  /*

   * Make a dedicated memory context for the CachedPlanSource and its

   * permanent subsidiary data.  It's probably not going to be large, but

   * just in case, allow it to grow large.  Initially it's a child of the

   * caller's context (which we assume to be transient), so that it will be

   * cleaned up on error.

   */

  source_context = AllocSetContextCreate(CurrentMemoryContext,

                       "CachedPlanSource",

                       ALLOCSET_START_SMALL_SIZES);

  /*

   * Create and fill the CachedPlanSource struct within the new context.

   * Most fields are just left empty for the moment.

   */

  oldcxt = MemoryContextSwitchTo(source_context);

  plansource = palloc0_object(CachedPlanSource);

  plansource->magic = CACHEDPLANSOURCE_MAGIC;

  plansource->raw_parse_tree = copyObject(raw_parse_tree);

  plansource->analyzed_parse_tree = NULL;

  plansource->query_string = pstrdup(query_string);

  MemoryContextSetIdentifier(source_context, plansource->query_string);

  plansource->commandTag = commandTag;

  plansource->param_types = NULL;

  plansource->num_params = 0;

  plansource->parserSetup = NULL;

  plansource->parserSetupArg = NULL;

  plansource->postRewrite = NULL;

  plansource->postRewriteArg = NULL;

  plansource->cursor_options = 0;

  plansource->fixed_result = false;

  plansource->resultDesc = NULL;

  plansource->context = source_context;

  plansource->query_list = NIL;

  plansource->relationOids = NIL;

  plansource->invalItems = NIL;

  plansource->search_path = NULL;

  plansource->query_context = NULL;

  plansource->rewriteRoleId = InvalidOid;

  plansource->rewriteRowSecurity = false;

  plansource->dependsOnRLS = false;

  plansource->gplan = NULL;

  plansource->is_oneshot = false;

  plansource->is_complete = false;

  plansource->is_saved = false;

  plansource->is_valid = false;

  plansource->generation = 0;

  plansource->generic_cost = -1;

  plansource->total_custom_cost = 0;

  plansource->num_generic_plans = 0;

  plansource->num_custom_plans = 0;

  MemoryContextSwitchTo(oldcxt);

  return plansource;

}

/*

 * CreateCachedPlanForQuery: initially create a plan cache entry for a Query.

 *

 * This is used in the same way as CreateCachedPlan, except that the source

 * query has already been through parse analysis, and the plancache will never

 * try to re-do that step.

 *

 * Currently this is used only for new-style SQL functions, where we have a

 * Query from the function's prosqlbody, but no source text.  The query_string

 * is typically empty, but is required anyway.

 */

CachedPlanSource *

CreateCachedPlanForQuery(Query *analyzed_parse_tree,

             const char *query_string,

             CommandTag commandTag)

{

  CachedPlanSource *plansource;

  MemoryContext oldcxt;

  /* Rather than duplicating CreateCachedPlan, just do this: */

  plansource = CreateCachedPlan(NULL, query_string, commandTag);

  oldcxt = MemoryContextSwitchTo(plansource->context);

  plansource->analyzed_parse_tree = copyObject(analyzed_parse_tree);

  MemoryContextSwitchTo(oldcxt);

  return plansource;

}

/*

 * CreateOneShotCachedPlan: initially create a one-shot plan cache entry.

 *

 * This variant of CreateCachedPlan creates a plan cache entry that is meant

 * to be used only once.  No data copying occurs: all data structures remain

 * in the caller's memory context (which typically should get cleared after

 * completing execution).  The CachedPlanSource struct itself is also created

 * in that context.

 *

 * A one-shot plan cannot be saved or copied, since we make no effort to

 * preserve the raw parse tree unmodified.  There is also no support for

 * invalidation, so plan use must be completed in the current transaction,

 * and DDL that might invalidate the querytree_list must be avoided as well.

 *

 * raw_parse_tree: output of raw_parser(), or NULL if empty query

 * query_string: original query text

 * commandTag: command tag for query, or NULL if empty query

 */

CachedPlanSource *

CreateOneShotCachedPlan(RawStmt *raw_parse_tree,

            const char *query_string,

            CommandTag commandTag)

{

  CachedPlanSource *plansource;

  Assert(query_string != NULL); /* required as of 8.4 */

  /*

   * Create and fill the CachedPlanSource struct within the caller's memory

   * context.  Most fields are just left empty for the moment.

   */

  plansource = palloc0_object(CachedPlanSource);

  plansource->magic = CACHEDPLANSOURCE_MAGIC;

  plansource->raw_parse_tree = raw_parse_tree;

  plansource->analyzed_parse_tree = NULL;

  plansource->query_string = query_string;

  plansource->commandTag = commandTag;

  plansource->param_types = NULL;

  plansource->num_params = 0;

  plansource->parserSetup = NULL;

  plansource->parserSetupArg = NULL;

  plansource->postRewrite = NULL;

  plansource->postRewriteArg = NULL;

  plansource->cursor_options = 0;

  plansource->fixed_result = false;

  plansource->resultDesc = NULL;

  plansource->context = CurrentMemoryContext;

  plansource->query_list = NIL;

  plansource->relationOids = NIL;

  plansource->invalItems = NIL;

  plansource->search_path = NULL;

  plansource->query_context = NULL;

  plansource->rewriteRoleId = InvalidOid;

  plansource->rewriteRowSecurity = false;

  plansource->dependsOnRLS = false;

  plansource->gplan = NULL;

  plansource->is_oneshot = true;

  plansource->is_complete = false;

  plansource->is_saved = false;

  plansource->is_valid = false;

  plansource->generation = 0;

  plansource->generic_cost = -1;

  plansource->total_custom_cost = 0;

  plansource->num_generic_plans = 0;

  plansource->num_custom_plans = 0;

  return plansource;

}

/*

 * CompleteCachedPlan: second step of creating a plan cache entry.

 *

 * Pass in the analyzed-and-rewritten form of the query, as well as the

 * required subsidiary data about parameters and such.  All passed values will

 * be copied into the CachedPlanSource's memory, except as specified below.

 * After this is called, GetCachedPlan can be called to obtain a plan, and

 * optionally the CachedPlanSource can be saved using SaveCachedPlan.

 *

 * If querytree_context is not NULL, the querytree_list must be stored in that

 * context (but the other parameters need not be).  The querytree_list is not

 * copied, rather the given context is kept as the initial query_context of

 * the CachedPlanSource.  (It should have been created as a child of the

 * caller's working memory context, but it will now be reparented to belong

 * to the CachedPlanSource.)  The querytree_context is normally the context in

 * which the caller did raw parsing and parse analysis.  This approach saves

 * one tree copying step compared to passing NULL, but leaves lots of extra

 * cruft in the query_context, namely whatever extraneous stuff parse analysis

 * created, as well as whatever went unused from the raw parse tree.  Using

 * this option is a space-for-time tradeoff that is appropriate if the

 * CachedPlanSource is not expected to survive long.

 *

 * plancache.c cannot know how to copy the data referenced by parserSetupArg,

 * and it would often be inappropriate to do so anyway.  When using that

 * option, it is caller's responsibility that the referenced data remains

 * valid for as long as the CachedPlanSource exists.

 *

 * If the CachedPlanSource is a "oneshot" plan, then no querytree copying

 * occurs at all, and querytree_context is ignored; it is caller's

 * responsibility that the passed querytree_list is sufficiently long-lived.

 *

 * plansource: structure returned by CreateCachedPlan

 * querytree_list: analyzed-and-rewritten form of query (list of Query nodes)

 * querytree_context: memory context containing querytree_list,

 *            or NULL to copy querytree_list into a fresh context

 * param_types: array of fixed parameter type OIDs, or NULL if none

 * num_params: number of fixed parameters

 * parserSetup: alternate method for handling query parameters

 * parserSetupArg: data to pass to parserSetup

 * cursor_options: options bitmask to pass to planner

 * fixed_result: true to disallow future changes in query's result tupdesc

 */

void

CompleteCachedPlan(CachedPlanSource *plansource,

           List *querytree_list,

           MemoryContext querytree_context,

           const Oid *param_types,

           int num_params,

           ParserSetupHook parserSetup,

           void *parserSetupArg,

           int cursor_options,

           bool fixed_result)

{

  MemoryContext source_context = plansource->context;

  MemoryContext oldcxt = CurrentMemoryContext;

  /* Assert caller is doing things in a sane order */

  Assert(plansource->magic == CACHEDPLANSOURCE_MAGIC);

  Assert(!plansource->is_complete);

  /*

   * If caller supplied a querytree_context, reparent it underneath the

   * CachedPlanSource's context; otherwise, create a suitable context and

   * copy the querytree_list into it.  But no data copying should be done

   * for one-shot plans; for those, assume the passed querytree_list is

   * sufficiently long-lived.

   */

  if (plansource->is_oneshot)

  {

    querytree_context = CurrentMemoryContext;

  }

  else if (querytree_context != NULL)

  {

    MemoryContextSetParent(querytree_context, source_context);

    MemoryContextSwitchTo(querytree_context);

  }

  else

  {

    /* Again, it's a good bet the querytree_context can be small */

    querytree_context = AllocSetContextCreate(source_context,

                          "CachedPlanQuery",

                          ALLOCSET_START_SMALL_SIZES);

    MemoryContextSwitchTo(querytree_context);

    querytree_list = copyObject(querytree_list);

  }

  plansource->query_context = querytree_context;

  plansource->query_list = querytree_list;

  if (!plansource->is_oneshot && StmtPlanRequiresRevalidation(plansource))

  {

    /*

     * Use the planner machinery to extract dependencies.  Data is saved

     * in query_context.  (We assume that not a lot of extra cruft is

     * created by this call.)  We can skip this for one-shot plans, and

     * plans not needing revalidation have no such dependencies anyway.

     */

    extract_query_dependencies((Node *) querytree_list,

                   &plansource->relationOids,

                   &plansource->invalItems,

                   &plansource->dependsOnRLS);

    /* Update RLS info as well. */

    plansource->rewriteRoleId = GetUserId();

    plansource->rewriteRowSecurity = row_security;

    /*

     * Also save the current search_path in the query_context.  (This

     * should not generate much extra cruft either, since almost certainly

     * the path is already valid.)  Again, we don't really need this for

     * one-shot plans; and we *must* skip this for transaction control

     * commands, because this could result in catalog accesses.

     */

    plansource->search_path = GetSearchPathMatcher(querytree_context);

  }

  /*

   * Save the final parameter types (or other parameter specification data)

   * into the source_context, as well as our other parameters.

   */

  MemoryContextSwitchTo(source_context);

  if (num_params > 0)

  {

    plansource->param_types = palloc_array(Oid, num_params);

    memcpy(plansource->param_types, param_types, num_params * sizeof(Oid));

  }

  else

    plansource->param_types = NULL;

  plansource->num_params = num_params;

  plansource->parserSetup = parserSetup;

  plansource->parserSetupArg = parserSetupArg;

  plansource->cursor_options = cursor_options;

  plansource->fixed_result = fixed_result;

  /*

   * Also save the result tuple descriptor.  PlanCacheComputeResultDesc may

   * leak some cruft; normally we just accept that to save a copy step, but

   * in USE_VALGRIND mode be tidy by running it in the caller's context.

   */

#ifdef USE_VALGRIND

  MemoryContextSwitchTo(oldcxt);

  plansource->resultDesc = PlanCacheComputeResultDesc(querytree_list);

  if (plansource->resultDesc)

  {

    MemoryContextSwitchTo(source_context);

    plansource->resultDesc = CreateTupleDescCopy(plansource->resultDesc);

    MemoryContextSwitchTo(oldcxt);

  }

#else

  plansource->resultDesc = PlanCacheComputeResultDesc(querytree_list);

  MemoryContextSwitchTo(oldcxt);

#endif

  plansource->is_complete = true;

  plansource->is_valid = true;

}

/*

 * SetPostRewriteHook: set a hook to modify post-rewrite query trees

 *

 * Some callers have a need to modify the query trees between rewriting and

 * planning.  In the initial call to CompleteCachedPlan, it's assumed such

 * work was already done on the querytree_list.  However, if we're forced

 * to replan, it will need to be done over.  The caller can set this hook

 * to provide code to make that happen.

 *

 * postRewriteArg is just passed verbatim to the hook.  As with parserSetupArg,

 * it is caller's responsibility that the referenced data remains

 * valid for as long as the CachedPlanSource exists.

 */

void

SetPostRewriteHook(CachedPlanSource *plansource,

           PostRewriteHook postRewrite,

           void *postRewriteArg)

{

  Assert(plansource->magic == CACHEDPLANSOURCE_MAGIC);

  plansource->postRewrite = postRewrite;

  plansource->postRewriteArg = postRewriteArg;

}

/*

 * SaveCachedPlan: save a cached plan permanently

 *

 * This function moves the cached plan underneath CacheMemoryContext (making

 * it live for the life of the backend, unless explicitly dropped), and adds

 * it to the list of cached plans that are checked for invalidation when an

 * sinval event occurs.

 *

 * This is guaranteed not to throw error, except for the caller-error case

 * of trying to save a one-shot plan.  Callers typically depend on that

 * since this is called just before or just after adding a pointer to the

 * CachedPlanSource to some permanent data structure of their own.  Up until

 * this is done, a CachedPlanSource is just transient data that will go away

 * automatically on transaction abort.

 */

void

SaveCachedPlan(CachedPlanSource *plansource)

{

  /* Assert caller is doing things in a sane order */

  Assert(plansource->magic == CACHEDPLANSOURCE_MAGIC);

  Assert(plansource->is_complete);

  Assert(!plansource->is_saved);

  /* This seems worth a real test, though */

  if (plansource->is_oneshot)

    elog(ERROR, "cannot save one-shot cached plan");

  /*

   * In typical use, this function would be called before generating any

   * plans from the CachedPlanSource.  If there is a generic plan, moving it

   * into CacheMemoryContext would be pretty risky since it's unclear

   * whether the caller has taken suitable care with making references

   * long-lived.  Best thing to do seems to be to discard the plan.

   */

  ReleaseGenericPlan(plansource);

  /*

   * Reparent the source memory context under CacheMemoryContext so that it

   * will live indefinitely.  The query_context follows along since it's

   * already a child of the other one.

   */

  MemoryContextSetParent(plansource->context, CacheMemoryContext);

  /*

   * Add the entry to the global list of cached plans.

   */

  dlist_push_tail(&saved_plan_list, &plansource->node);

  plansource->is_saved = true;

}

/*

 * DropCachedPlan: destroy a cached plan.

 *

 * Actually this only destroys the CachedPlanSource: any referenced CachedPlan

 * is released, but not destroyed until its refcount goes to zero.  That

 * handles the situation where DropCachedPlan is called while the plan is

 * still in use.

 */

void

DropCachedPlan(CachedPlanSource *plansource)

{

  Assert(plansource->magic == CACHEDPLANSOURCE_MAGIC);

  /* If it's been saved, remove it from the list */

  if (plansource->is_saved)

  {

    dlist_delete(&plansource->node);

    plansource->is_saved = false;

  }

  /* Decrement generic CachedPlan's refcount and drop if no longer needed */

  ReleaseGenericPlan(plansource);

  /* Mark it no longer valid */

  plansource->magic = 0;

  /*

   * Remove the CachedPlanSource and all subsidiary data (including the

   * query_context if any).  But if it's a one-shot we can't free anything.

   */

  if (!plansource->is_oneshot)

    MemoryContextDelete(plansource->context);

}

/*

 * ReleaseGenericPlan: release a CachedPlanSource's generic plan, if any.

 */

static void

ReleaseGenericPlan(CachedPlanSource *plansource)

{

  /* Be paranoid about the possibility that ReleaseCachedPlan fails */

  if (plansource->gplan)

  {

    CachedPlan *plan = plansource->gplan;

    Assert(plan->magic == CACHEDPLAN_MAGIC);

    plansource->gplan = NULL;

    ReleaseCachedPlan(plan, NULL);

  }

}

/*

 * We must skip "overhead" operations that involve database access when the

 * cached plan's subject statement is a transaction control command or one

 * that requires a snapshot not to be set yet (such as SET or LOCK).  More

 * generally, statements that do not require parse analysis/rewrite/plan

 * activity never need to be revalidated, so we can treat them all like that.

 * For the convenience of postgres.c, treat empty statements that way too.

 */

static bool

StmtPlanRequiresRevalidation(CachedPlanSource *plansource)

{

  if (plansource->raw_parse_tree != NULL)

    return stmt_requires_parse_analysis(plansource->raw_parse_tree);

  else if (plansource->analyzed_parse_tree != NULL)

    return query_requires_rewrite_plan(plansource->analyzed_parse_tree);

  /* empty query never needs revalidation */

  return false;

}

/*

 * Determine if creating a plan for this CachedPlanSource requires a snapshot.

 * In fact this function matches StmtPlanRequiresRevalidation(), but we want

 * to preserve the distinction between stmt_requires_parse_analysis() and

 * analyze_requires_snapshot().

 */

static bool

BuildingPlanRequiresSnapshot(CachedPlanSource *plansource)

{

  if (plansource->raw_parse_tree != NULL)

    return analyze_requires_snapshot(plansource->raw_parse_tree);

  else if (plansource->analyzed_parse_tree != NULL)

    return query_requires_rewrite_plan(plansource->analyzed_parse_tree);

  /* empty query never needs a snapshot */

  return false;

}

/*

 * RevalidateCachedQuery: ensure validity of analyzed-and-rewritten query tree.

 *

 * What we do here is re-acquire locks and redo parse analysis if necessary.

 * On return, the query_list is valid and we have sufficient locks to begin

 * planning.

 *

 * If any parse analysis activity is required, the caller's memory context is

 * used for that work.

 *

 * The result value is the transient analyzed-and-rewritten query tree if we

 * had to do re-analysis, and NIL otherwise.  (This is returned just to save

 * a tree copying step in a subsequent BuildCachedPlan call.)

 */

static List *

RevalidateCachedQuery(CachedPlanSource *plansource,

            QueryEnvironment *queryEnv)

{

  bool    snapshot_set;

  List     *tlist;      /* transient query-tree list */

  List     *qlist;      /* permanent query-tree list */

  TupleDesc resultDesc;

  MemoryContext querytree_context;

  MemoryContext oldcxt;

  /*

   * For one-shot plans, we do not support revalidation checking; it's

   * assumed the query is parsed, planned, and executed in one transaction,

   * so that no lock re-acquisition is necessary.  Also, if the statement

   * type can't require revalidation, we needn't do anything (and we mustn't

   * risk catalog accesses when handling, eg, transaction control commands).

   */

  if (plansource->is_oneshot || !StmtPlanRequiresRevalidation(plansource))

  {

    Assert(plansource->is_valid);

    return NIL;

  }

  /*

   * If the query is currently valid, we should have a saved search_path ---

   * check to see if that matches the current environment.  If not, we want

   * to force replan.  (We could almost ignore this consideration when

   * working from an analyzed parse tree; but there are scenarios where

   * planning can have search_path-dependent results, for example if it

   * inlines an old-style SQL function.)

   */

  if (plansource->is_valid)

  {

    Assert(plansource->search_path != NULL);

    if (!SearchPathMatchesCurrentEnvironment(plansource->search_path))

    {

      /* Invalidate the querytree and generic plan */

      plansource->is_valid = false;

      if (plansource->gplan)

        plansource->gplan->is_valid = false;

    }

  }

  /*

   * If the query rewrite phase had a possible RLS dependency, we must redo

   * it if either the role or the row_security setting has changed.

   */

  if (plansource->is_valid && plansource->dependsOnRLS &&

    (plansource->rewriteRoleId != GetUserId() ||

     plansource->rewriteRowSecurity != row_security))

    plansource->is_valid = false;

  /*

   * If the query is currently valid, acquire locks on the referenced

   * objects; then check again.  We need to do it this way to cover the race

   * condition that an invalidation message arrives before we get the locks.

   */

  if (plansource->is_valid)

  {

    AcquirePlannerLocks(plansource->query_list, true);

    /*

     * By now, if any invalidation has happened, the inval callback

     * functions will have marked the query invalid.

     */

    if (plansource->is_valid)

    {

      /* Successfully revalidated and locked the query. */

      return NIL;

    }

    /* Oops, the race case happened.  Release useless locks. */

    AcquirePlannerLocks(plansource->query_list, false);

  }

  /*

   * Discard the no-longer-useful rewritten query tree.  (Note: we don't

   * want to do this any earlier, else we'd not have been able to release

   * locks correctly in the race condition case.)

   */

  plansource->is_valid = false;

  plansource->query_list = NIL;

  plansource->relationOids = NIL;

  plansource->invalItems = NIL;

  plansource->search_path = NULL;

  /*

   * Free the query_context.  We don't really expect MemoryContextDelete to

   * fail, but just in case, make sure the CachedPlanSource is left in a

   * reasonably sane state.  (The generic plan won't get unlinked yet, but

   * that's acceptable.)

   */

  if (plansource->query_context)

  {

    MemoryContext qcxt = plansource->query_context;

    plansource->query_context = NULL;

    MemoryContextDelete(qcxt);

  }

  /* Drop the generic plan reference if any */

  ReleaseGenericPlan(plansource);

  /*

   * Now re-do parse analysis and rewrite.  This not incidentally acquires

   * the locks we need to do planning safely.

   */

  Assert(plansource->is_complete);

  /*

   * If a snapshot is already set (the normal case), we can just use that

   * for parsing/planning.  But if it isn't, install one.  Note: no point in

   * checking whether parse analysis requires a snapshot; utility commands

   * don't have invalidatable plans, so we'd not get here for such a

   * command.

   */

  snapshot_set = false;

  if (!ActiveSnapshotSet())

  {

    PushActiveSnapshot(GetTransactionSnapshot());

    snapshot_set = true;

  }

  /*

   * Run parse analysis (if needed) and rule rewriting.

   */

  if (plansource->raw_parse_tree != NULL)

  {

    /* Source is raw parse tree */

    RawStmt    *rawtree;

    /*

     * The parser tends to scribble on its input, so we must copy the raw

     * parse tree to prevent corruption of the cache.

     */

    rawtree = copyObject(plansource->raw_parse_tree);

    if (plansource->parserSetup != NULL)

      tlist = pg_analyze_and_rewrite_withcb(rawtree,

                          plansource->query_string,

                          plansource->parserSetup,

                          plansource->parserSetupArg,

                          queryEnv);

    else

      tlist = pg_analyze_and_rewrite_fixedparams(rawtree,

                             plansource->query_string,

                             plansource->param_types,

                             plansource->num_params,

                             queryEnv);

  }

  else if (plansource->analyzed_parse_tree != NULL)

  {

    /* Source is pre-analyzed query, so we only need to rewrite */

    Query    *analyzed_tree;

    /* The rewriter scribbles on its input, too, so copy */

    analyzed_tree = copyObject(plansource->analyzed_parse_tree);

    /* Acquire locks needed before rewriting ... */

    AcquireRewriteLocks(analyzed_tree, true, false);

    /* ... and do it */

    tlist = pg_rewrite_query(analyzed_tree);

  }

  else

  {

    /* Empty query, nothing to do */

    tlist = NIL;

  }

  /* Apply post-rewrite callback if there is one */

  if (plansource->postRewrite != NULL)

    plansource->postRewrite(tlist, plansource->postRewriteArg);

  /* Release snapshot if we got one */

  if (snapshot_set)

    PopActiveSnapshot();

  /*

   * Check or update the result tupdesc.

   *

   * We assume the parameter types didn't change from the first time, so no

   * need to update that.

   */

  resultDesc = PlanCacheComputeResultDesc(tlist);

  if (resultDesc == NULL && plansource->resultDesc == NULL)

  {

    /* OK, doesn't return tuples */

  }

  else if (resultDesc == NULL || plansource->resultDesc == NULL ||

       !equalRowTypes(resultDesc, plansource->resultDesc))

  {

    /* can we give a better error message? */

    if (plansource->fixed_result)

      ereport(ERROR,

          (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),

           errmsg("cached plan must not change result type")));

    oldcxt = MemoryContextSwitchTo(plansource->context);

    if (resultDesc)

      resultDesc = CreateTupleDescCopy(resultDesc);

    if (plansource->resultDesc)

      FreeTupleDesc(plansource->resultDesc);

    plansource->resultDesc = resultDesc;

    MemoryContextSwitchTo(oldcxt);

  }

  /*

   * Allocate new query_context and copy the completed querytree into it.

   * It's transient until we complete the copying and dependency extraction.

   */

  querytree_context = AllocSetContextCreate(CurrentMemoryContext,

                        "CachedPlanQuery",

                        ALLOCSET_START_SMALL_SIZES);

  oldcxt = MemoryContextSwitchTo(querytree_context);

  qlist = copyObject(tlist);

  /*

   * Use the planner machinery to extract dependencies.  Data is saved in

   * query_context.  (We assume that not a lot of extra cruft is created by

   * this call.)

   */

  extract_query_dependencies((Node *) qlist,

                 &plansource->relationOids,

                 &plansource->invalItems,

                 &plansource->dependsOnRLS);

  /* Update RLS info as well. */

  plansource->rewriteRoleId = GetUserId();

  plansource->rewriteRowSecurity = row_security;

  /*

   * Also save the current search_path in the query_context.  (This should

   * not generate much extra cruft either, since almost certainly the path

   * is already valid.)

   */

  plansource->search_path = GetSearchPathMatcher(querytree_context);

  MemoryContextSwitchTo(oldcxt);

  /* Now reparent the finished query_context and save the links */

  MemoryContextSetParent(querytree_context, plansource->context);

  plansource->query_context = querytree_context;

  plansource->query_list = qlist;

  /*

   * Note: we do not reset generic_cost or total_custom_cost, although we

   * could choose to do so.  If the DDL or statistics change that prompted

   * the invalidation meant a significant change in the cost estimates, it

   * would be better to reset those variables and start fresh; but often it

   * doesn't, and we're better retaining our hard-won knowledge about the

   * relative costs.

   */

  plansource->is_valid = true;

  /* Return transient copy of querytrees for possible use in planning */

  return tlist;

}

/*

 * CheckCachedPlan: see if the CachedPlanSource's generic plan is valid.

 *

 * Caller must have already called RevalidateCachedQuery to verify that the

 * querytree is up to date.

 *

 * On a "true" return, we have acquired the locks needed to run the plan.

 * (We must do this for the "true" result to be race-condition-free.)

 */

static bool

CheckCachedPlan(CachedPlanSource *plansource)

{

  CachedPlan *plan = plansource->gplan;

  /* Assert that caller checked the querytree */

  Assert(plansource->is_valid);

  /* If there's no generic plan, just say "false" */

  if (!plan)

    return false;

  Assert(plan->magic == CACHEDPLAN_MAGIC);

  /* Generic plans are never one-shot */

  Assert(!plan->is_oneshot);

  /*

   * If plan isn't valid for current role, we can't use it.

   */

  if (plan->is_valid && plan->dependsOnRole &&

    plan->planRoleId != GetUserId())

    plan->is_valid = false;

  /*

   * If it appears valid, acquire locks and recheck; this is much the same