Debian Codegraph @

src/backend/utils/cache/plancache.c

raw
1 /*-------------------------------------------------------------------------
2 *
3 * plancache.c
4 * Plan cache management.
5 *
6 * The plan cache manager has two principal responsibilities: deciding when
7 * to use a generic plan versus a custom (parameter-value-specific) plan,
8 * and tracking whether cached plans need to be invalidated because of schema
9 * changes in the objects they depend on.
10 *
11 * The logic for choosing generic or custom plans is in choose_custom_plan,
12 * which see for comments.
13 *
14 * Cache invalidation is driven off sinval events. Any CachedPlanSource
15 * that matches the event is marked invalid, as is its generic CachedPlan
16 * if it has one. When (and if) the next demand for a cached plan occurs,
17 * parse analysis and/or rewrite is repeated to build a new valid query tree,
18 * and then planning is performed as normal. We also force re-analysis and
19 * re-planning if the active search_path is different from the previous time
20 * or, if RLS is involved, if the user changes or the RLS environment changes.
21 *
22 * Note that if the sinval was a result of user DDL actions, parse analysis
23 * could throw an error, for example if a column referenced by the query is
24 * no longer present. Another possibility is for the query's output tupdesc
25 * to change (for instance "SELECT *" might expand differently than before).
26 * The creator of a cached plan can specify whether it is allowable for the
27 * query to change output tupdesc on replan --- if so, it's up to the
28 * caller to notice changes and cope with them.
29 *
30 * Currently, we track exactly the dependencies of plans on relations,
31 * user-defined functions, and domains. On relcache invalidation events or
32 * pg_proc or pg_type syscache invalidation events, we invalidate just those
33 * plans that depend on the particular object being modified. (Note: this
34 * scheme assumes that any table modification that requires replanning will
35 * generate a relcache inval event.) We also watch for inval events on
36 * certain other system catalogs, such as pg_namespace; but for them, our
37 * response is just to invalidate all plans. We expect updates on those
38 * catalogs to be infrequent enough that more-detailed tracking is not worth
39 * the effort. We likewise watch pg_authid, pg_auth_members, and
40 * pg_database, which can change which row-level security policies apply.
41 * Since those are shared catalogs whose inval events reach every backend
42 * in the cluster, we invalidate only the role-dependent plans.
43 *
44 * In addition to full-fledged query plans, we provide a facility for
45 * detecting invalidations of simple scalar expressions. This is fairly
46 * bare-bones; it's the caller's responsibility to build a new expression
47 * if the old one gets invalidated.
48 *
49 *
50 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
51 * Portions Copyright (c) 1994, Regents of the University of California
52 *
53 * IDENTIFICATION
54 * src/backend/utils/cache/plancache.c
55 *
56 *-------------------------------------------------------------------------
57 */
58 #include "postgres.h"
59
60 #include <limits.h>
61
62 #include "access/transam.h"
63 #include "catalog/namespace.h"
64 #include "executor/executor.h"
65 #include "miscadmin.h"
66 #include "nodes/nodeFuncs.h"
67 #include "optimizer/optimizer.h"
68 #include "parser/analyze.h"
69 #include "rewrite/rewriteHandler.h"
70 #include "storage/lmgr.h"
71 #include "tcop/pquery.h"
72 #include "tcop/utility.h"
73 #include "utils/acl.h"
74 #include "utils/inval.h"
75 #include "utils/memutils.h"
76 #include "utils/resowner.h"
77 #include "utils/rls.h"
78 #include "utils/snapmgr.h"
79 #include "utils/syscache.h"
80
81
82 /*
83 * This is the head of the backend's list of "saved" CachedPlanSources (i.e.,
84 * those that are in long-lived storage and are examined for sinval events).
85 * We use a dlist instead of separate List cells so that we can guarantee
86 * to save a CachedPlanSource without error.
87 */
88 static dlist_head saved_plan_list = DLIST_STATIC_INIT(saved_plan_list);
89
90 /*
91 * This is the head of the backend's list of CachedExpressions.
92 */
93 static dlist_head cached_expression_list = DLIST_STATIC_INIT(cached_expression_list);
94
95 static void ReleaseGenericPlan(CachedPlanSource *plansource);
96 static bool StmtPlanRequiresRevalidation(CachedPlanSource *plansource);
97 static bool BuildingPlanRequiresSnapshot(CachedPlanSource *plansource);
98 static List *RevalidateCachedQuery(CachedPlanSource *plansource,
99 QueryEnvironment *queryEnv);
100 static bool CheckCachedPlan(CachedPlanSource *plansource);
101 static CachedPlan *BuildCachedPlan(CachedPlanSource *plansource, List *qlist,
102 ParamListInfo boundParams, QueryEnvironment *queryEnv);
103 static bool choose_custom_plan(CachedPlanSource *plansource,
104 ParamListInfo boundParams);
105 static double cached_plan_cost(CachedPlan *plan, bool include_planner);
106 static Query *QueryListGetPrimaryStmt(List *stmts);
107 static void AcquireExecutorLocks(List *stmt_list, bool acquire);
108 static void AcquirePlannerLocks(List *stmt_list, bool acquire);
109 static void ScanQueryForLocks(Query *parsetree, bool acquire);
110 static bool ScanQueryWalker(Node *node, bool *acquire);
111 static TupleDesc PlanCacheComputeResultDesc(List *stmt_list);
112 static void PlanCacheRelCallback(Datum arg, Oid relid);
113 static void PlanCacheObjectCallback(Datum arg, int cacheid, uint32 hashvalue);
114 static void PlanCacheRoleCallback(Datum arg, int cacheid, uint32 hashvalue);
115 static void PlanCacheSysCallback(Datum arg, int cacheid, uint32 hashvalue);
116
117 /* ResourceOwner callbacks to track plancache references */
118 static void ResOwnerReleaseCachedPlan(Datum res);
119
120 static const ResourceOwnerDesc planref_resowner_desc =
121 {
122 .name = "plancache reference",
123 .release_phase = RESOURCE_RELEASE_AFTER_LOCKS,
124 .release_priority = RELEASE_PRIO_PLANCACHE_REFS,
125 .ReleaseResource = ResOwnerReleaseCachedPlan,
126 .DebugPrint = NULL /* the default message is fine */
127 };
128
129 /* Convenience wrappers over ResourceOwnerRemember/Forget */
130 static inline void
131 ResourceOwnerRememberPlanCacheRef(ResourceOwner owner, CachedPlan *plan)
132 {
133 ResourceOwnerRemember(owner, PointerGetDatum(plan), &planref_resowner_desc);
134 }
135 static inline void
136 ResourceOwnerForgetPlanCacheRef(ResourceOwner owner, CachedPlan *plan)
137 {
138 ResourceOwnerForget(owner, PointerGetDatum(plan), &planref_resowner_desc);
139 }
140
141
142 /* GUC parameter */
143 int plan_cache_mode = PLAN_CACHE_MODE_AUTO;
144
145 /*
146 * InitPlanCache: initialize module during InitPostgres.
147 *
148 * All we need to do is hook into inval.c's callback lists.
149 */
150 void
151 InitPlanCache(void)
152 {
153 CacheRegisterRelcacheCallback(PlanCacheRelCallback, (Datum) 0);
154 CacheRegisterSyscacheCallback(PROCOID, PlanCacheObjectCallback, (Datum) 0);
155 CacheRegisterSyscacheCallback(TYPEOID, PlanCacheObjectCallback, (Datum) 0);
156 CacheRegisterSyscacheCallback(NAMESPACEOID, PlanCacheSysCallback, (Datum) 0);
157 CacheRegisterSyscacheCallback(OPEROID, PlanCacheSysCallback, (Datum) 0);
158 CacheRegisterSyscacheCallback(AMOPOPID, PlanCacheSysCallback, (Datum) 0);
159 CacheRegisterSyscacheCallback(FOREIGNSERVEROID, PlanCacheSysCallback, (Datum) 0);
160 CacheRegisterSyscacheCallback(FOREIGNDATAWRAPPEROID, PlanCacheSysCallback, (Datum) 0);
161 CacheRegisterSyscacheCallback(AUTHMEMROLEMEM, PlanCacheRoleCallback, (Datum) 0);
162 CacheRegisterSyscacheCallback(AUTHOID, PlanCacheRoleCallback, (Datum) 0);
163 CacheRegisterSyscacheCallback(DATABASEOID, PlanCacheRoleCallback, (Datum) 0);
164 }
165
166 /*
167 * CreateCachedPlan: initially create a plan cache entry for a raw parse tree.
168 *
169 * Creation of a cached plan is divided into two steps, CreateCachedPlan and
170 * CompleteCachedPlan. CreateCachedPlan should be called after running the
171 * query through raw_parser, but before doing parse analysis and rewrite;
172 * CompleteCachedPlan is called after that. The reason for this arrangement
173 * is that it can save one round of copying of the raw parse tree, since
174 * the parser will normally scribble on the raw parse tree. Callers would
175 * otherwise need to make an extra copy of the parse tree to ensure they
176 * still had a clean copy to present at plan cache creation time.
177 *
178 * All arguments presented to CreateCachedPlan are copied into a memory
179 * context created as a child of the call-time CurrentMemoryContext, which
180 * should be a reasonably short-lived working context that will go away in
181 * event of an error. This ensures that the cached plan data structure will
182 * likewise disappear if an error occurs before we have fully constructed it.
183 * Once constructed, the cached plan can be made longer-lived, if needed,
184 * by calling SaveCachedPlan.
185 *
186 * raw_parse_tree: output of raw_parser(), or NULL if empty query
187 * query_string: original query text
188 * commandTag: command tag for query, or UNKNOWN if empty query
189 */
190 CachedPlanSource *
191 CreateCachedPlan(RawStmt *raw_parse_tree,
192 const char *query_string,
193 CommandTag commandTag)
194 {
195 CachedPlanSource *plansource;
196 MemoryContext source_context;
197 MemoryContext oldcxt;
198
199 Assert(query_string != NULL); /* required as of 8.4 */
200
201 /*
202 * Make a dedicated memory context for the CachedPlanSource and its
203 * permanent subsidiary data. It's probably not going to be large, but
204 * just in case, allow it to grow large. Initially it's a child of the
205 * caller's context (which we assume to be transient), so that it will be
206 * cleaned up on error.
207 */
208 source_context = AllocSetContextCreate(CurrentMemoryContext,
209 "CachedPlanSource",
210 ALLOCSET_START_SMALL_SIZES);
211
212 /*
213 * Create and fill the CachedPlanSource struct within the new context.
214 * Most fields are just left empty for the moment.
215 */
216 oldcxt = MemoryContextSwitchTo(source_context);
217
218 plansource = (CachedPlanSource *) palloc0(sizeof(CachedPlanSource));
219 plansource->magic = CACHEDPLANSOURCE_MAGIC;
220 plansource->raw_parse_tree = copyObject(raw_parse_tree);
221 plansource->analyzed_parse_tree = NULL;
222 plansource->query_string = pstrdup(query_string);
223 MemoryContextSetIdentifier(source_context, plansource->query_string);
224 plansource->commandTag = commandTag;
225 plansource->param_types = NULL;
226 plansource->num_params = 0;
227 plansource->parserSetup = NULL;
228 plansource->parserSetupArg = NULL;
229 plansource->postRewrite = NULL;
230 plansource->postRewriteArg = NULL;
231 plansource->cursor_options = 0;
232 plansource->fixed_result = false;
233 plansource->resultDesc = NULL;
234 plansource->context = source_context;
235 plansource->query_list = NIL;
236 plansource->relationOids = NIL;
237 plansource->invalItems = NIL;
238 plansource->search_path = NULL;
239 plansource->query_context = NULL;
240 plansource->rewriteRoleId = InvalidOid;
241 plansource->rewriteRowSecurity = false;
242 plansource->dependsOnRLS = false;
243 plansource->gplan = NULL;
244 plansource->is_oneshot = false;
245 plansource->is_complete = false;
246 plansource->is_saved = false;
247 plansource->is_valid = false;
248 plansource->generation = 0;
249 plansource->generic_cost = -1;
250 plansource->total_custom_cost = 0;
251 plansource->num_generic_plans = 0;
252 plansource->num_custom_plans = 0;
253
254 MemoryContextSwitchTo(oldcxt);
255
256 return plansource;
257 }
258
259 /*
260 * CreateCachedPlanForQuery: initially create a plan cache entry for a Query.
261 *
262 * This is used in the same way as CreateCachedPlan, except that the source
263 * query has already been through parse analysis, and the plancache will never
264 * try to re-do that step.
265 *
266 * Currently this is used only for new-style SQL functions, where we have a
267 * Query from the function's prosqlbody, but no source text. The query_string
268 * is typically empty, but is required anyway.
269 */
270 CachedPlanSource *
271 CreateCachedPlanForQuery(Query *analyzed_parse_tree,
272 const char *query_string,
273 CommandTag commandTag)
274 {
275 CachedPlanSource *plansource;
276 MemoryContext oldcxt;
277
278 /* Rather than duplicating CreateCachedPlan, just do this: */
279 plansource = CreateCachedPlan(NULL, query_string, commandTag);
280 oldcxt = MemoryContextSwitchTo(plansource->context);
281 plansource->analyzed_parse_tree = copyObject(analyzed_parse_tree);
282 MemoryContextSwitchTo(oldcxt);
283
284 return plansource;
285 }
286
287 /*
288 * CreateOneShotCachedPlan: initially create a one-shot plan cache entry.
289 *
290 * This variant of CreateCachedPlan creates a plan cache entry that is meant
291 * to be used only once. No data copying occurs: all data structures remain
292 * in the caller's memory context (which typically should get cleared after
293 * completing execution). The CachedPlanSource struct itself is also created
294 * in that context.
295 *
296 * A one-shot plan cannot be saved or copied, since we make no effort to
297 * preserve the raw parse tree unmodified. There is also no support for
298 * invalidation, so plan use must be completed in the current transaction,
299 * and DDL that might invalidate the querytree_list must be avoided as well.
300 *
301 * raw_parse_tree: output of raw_parser(), or NULL if empty query
302 * query_string: original query text
303 * commandTag: command tag for query, or NULL if empty query
304 */
305 CachedPlanSource *
306 CreateOneShotCachedPlan(RawStmt *raw_parse_tree,
307 const char *query_string,
308 CommandTag commandTag)
309 {
310 CachedPlanSource *plansource;
311
312 Assert(query_string != NULL); /* required as of 8.4 */
313
314 /*
315 * Create and fill the CachedPlanSource struct within the caller's memory
316 * context. Most fields are just left empty for the moment.
317 */
318 plansource = (CachedPlanSource *) palloc0(sizeof(CachedPlanSource));
319 plansource->magic = CACHEDPLANSOURCE_MAGIC;
320 plansource->raw_parse_tree = raw_parse_tree;
321 plansource->analyzed_parse_tree = NULL;
322 plansource->query_string = query_string;
323 plansource->commandTag = commandTag;
324 plansource->param_types = NULL;
325 plansource->num_params = 0;
326 plansource->parserSetup = NULL;
327 plansource->parserSetupArg = NULL;
328 plansource->postRewrite = NULL;
329 plansource->postRewriteArg = NULL;
330 plansource->cursor_options = 0;
331 plansource->fixed_result = false;
332 plansource->resultDesc = NULL;
333 plansource->context = CurrentMemoryContext;
334 plansource->query_list = NIL;
335 plansource->relationOids = NIL;
336 plansource->invalItems = NIL;
337 plansource->search_path = NULL;
338 plansource->query_context = NULL;
339 plansource->rewriteRoleId = InvalidOid;
340 plansource->rewriteRowSecurity = false;
341 plansource->dependsOnRLS = false;
342 plansource->gplan = NULL;
343 plansource->is_oneshot = true;
344 plansource->is_complete = false;
345 plansource->is_saved = false;
346 plansource->is_valid = false;
347 plansource->generation = 0;
348 plansource->generic_cost = -1;
349 plansource->total_custom_cost = 0;
350 plansource->num_generic_plans = 0;
351 plansource->num_custom_plans = 0;
352
353 return plansource;
354 }
355
356 /*
357 * CompleteCachedPlan: second step of creating a plan cache entry.
358 *
359 * Pass in the analyzed-and-rewritten form of the query, as well as the
360 * required subsidiary data about parameters and such. All passed values will
361 * be copied into the CachedPlanSource's memory, except as specified below.
362 * After this is called, GetCachedPlan can be called to obtain a plan, and
363 * optionally the CachedPlanSource can be saved using SaveCachedPlan.
364 *
365 * If querytree_context is not NULL, the querytree_list must be stored in that
366 * context (but the other parameters need not be). The querytree_list is not
367 * copied, rather the given context is kept as the initial query_context of
368 * the CachedPlanSource. (It should have been created as a child of the
369 * caller's working memory context, but it will now be reparented to belong
370 * to the CachedPlanSource.) The querytree_context is normally the context in
371 * which the caller did raw parsing and parse analysis. This approach saves
372 * one tree copying step compared to passing NULL, but leaves lots of extra
373 * cruft in the query_context, namely whatever extraneous stuff parse analysis
374 * created, as well as whatever went unused from the raw parse tree. Using
375 * this option is a space-for-time tradeoff that is appropriate if the
376 * CachedPlanSource is not expected to survive long.
377 *
378 * plancache.c cannot know how to copy the data referenced by parserSetupArg,
379 * and it would often be inappropriate to do so anyway. When using that
380 * option, it is caller's responsibility that the referenced data remains
381 * valid for as long as the CachedPlanSource exists.
382 *
383 * If the CachedPlanSource is a "oneshot" plan, then no querytree copying
384 * occurs at all, and querytree_context is ignored; it is caller's
385 * responsibility that the passed querytree_list is sufficiently long-lived.
386 *
387 * plansource: structure returned by CreateCachedPlan
388 * querytree_list: analyzed-and-rewritten form of query (list of Query nodes)
389 * querytree_context: memory context containing querytree_list,
390 * or NULL to copy querytree_list into a fresh context
391 * param_types: array of fixed parameter type OIDs, or NULL if none
392 * num_params: number of fixed parameters
393 * parserSetup: alternate method for handling query parameters
394 * parserSetupArg: data to pass to parserSetup
395 * cursor_options: options bitmask to pass to planner
396 * fixed_result: true to disallow future changes in query's result tupdesc
397 */
398 void
399 CompleteCachedPlan(CachedPlanSource *plansource,
400 List *querytree_list,
401 MemoryContext querytree_context,
402 Oid *param_types,
403 int num_params,
404 ParserSetupHook parserSetup,
405 void *parserSetupArg,
406 int cursor_options,
407 bool fixed_result)
408 {
409 MemoryContext source_context = plansource->context;
410 MemoryContext oldcxt = CurrentMemoryContext;
411
412 /* Assert caller is doing things in a sane order */
413 Assert(plansource->magic == CACHEDPLANSOURCE_MAGIC);
414 Assert(!plansource->is_complete);
415
416 /*
417 * If caller supplied a querytree_context, reparent it underneath the
418 * CachedPlanSource's context; otherwise, create a suitable context and
419 * copy the querytree_list into it. But no data copying should be done
420 * for one-shot plans; for those, assume the passed querytree_list is
421 * sufficiently long-lived.
422 */
423 if (plansource->is_oneshot)
424 {
425 querytree_context = CurrentMemoryContext;
426 }
427 else if (querytree_context != NULL)
428 {
429 MemoryContextSetParent(querytree_context, source_context);
430 MemoryContextSwitchTo(querytree_context);
431 }
432 else
433 {
434 /* Again, it's a good bet the querytree_context can be small */
435 querytree_context = AllocSetContextCreate(source_context,
436 "CachedPlanQuery",
437 ALLOCSET_START_SMALL_SIZES);
438 MemoryContextSwitchTo(querytree_context);
439 querytree_list = copyObject(querytree_list);
440 }
441
442 plansource->query_context = querytree_context;
443 plansource->query_list = querytree_list;
444
445 if (!plansource->is_oneshot && StmtPlanRequiresRevalidation(plansource))
446 {
447 /*
448 * Use the planner machinery to extract dependencies. Data is saved
449 * in query_context. (We assume that not a lot of extra cruft is
450 * created by this call.) We can skip this for one-shot plans, and
451 * plans not needing revalidation have no such dependencies anyway.
452 */
453 extract_query_dependencies((Node *) querytree_list,
454 &plansource->relationOids,
455 &plansource->invalItems,
456 &plansource->dependsOnRLS);
457
458 /* Update RLS info as well. */
459 plansource->rewriteRoleId = GetUserId();
460 plansource->rewriteRowSecurity = row_security;
461
462 /*
463 * Also save the current search_path in the query_context. (This
464 * should not generate much extra cruft either, since almost certainly
465 * the path is already valid.) Again, we don't really need this for
466 * one-shot plans; and we *must* skip this for transaction control
467 * commands, because this could result in catalog accesses.
468 */
469 plansource->search_path = GetSearchPathMatcher(querytree_context);
470 }
471
472 /*
473 * Save the final parameter types (or other parameter specification data)
474 * into the source_context, as well as our other parameters. Also save
475 * the result tuple descriptor.
476 */
477 MemoryContextSwitchTo(source_context);
478
479 if (num_params > 0)
480 {
481 plansource->param_types = (Oid *) palloc(num_params * sizeof(Oid));
482 memcpy(plansource->param_types, param_types, num_params * sizeof(Oid));
483 }
484 else
485 plansource->param_types = NULL;
486 plansource->num_params = num_params;
487 plansource->parserSetup = parserSetup;
488 plansource->parserSetupArg = parserSetupArg;
489 plansource->cursor_options = cursor_options;
490 plansource->fixed_result = fixed_result;
491 plansource->resultDesc = PlanCacheComputeResultDesc(querytree_list);
492
493 MemoryContextSwitchTo(oldcxt);
494
495 plansource->is_complete = true;
496 plansource->is_valid = true;
497 }
498
499 /*
500 * SetPostRewriteHook: set a hook to modify post-rewrite query trees
501 *
502 * Some callers have a need to modify the query trees between rewriting and
503 * planning. In the initial call to CompleteCachedPlan, it's assumed such
504 * work was already done on the querytree_list. However, if we're forced
505 * to replan, it will need to be done over. The caller can set this hook
506 * to provide code to make that happen.
507 *
508 * postRewriteArg is just passed verbatim to the hook. As with parserSetupArg,
509 * it is caller's responsibility that the referenced data remains
510 * valid for as long as the CachedPlanSource exists.
511 */
512 void
513 SetPostRewriteHook(CachedPlanSource *plansource,
514 PostRewriteHook postRewrite,
515 void *postRewriteArg)
516 {
517 Assert(plansource->magic == CACHEDPLANSOURCE_MAGIC);
518 plansource->postRewrite = postRewrite;
519 plansource->postRewriteArg = postRewriteArg;
520 }
521
522 /*
523 * SaveCachedPlan: save a cached plan permanently
524 *
525 * This function moves the cached plan underneath CacheMemoryContext (making
526 * it live for the life of the backend, unless explicitly dropped), and adds
527 * it to the list of cached plans that are checked for invalidation when an
528 * sinval event occurs.
529 *
530 * This is guaranteed not to throw error, except for the caller-error case
531 * of trying to save a one-shot plan. Callers typically depend on that
532 * since this is called just before or just after adding a pointer to the
533 * CachedPlanSource to some permanent data structure of their own. Up until
534 * this is done, a CachedPlanSource is just transient data that will go away
535 * automatically on transaction abort.
536 */
537 void
538 SaveCachedPlan(CachedPlanSource *plansource)
539 {
540 /* Assert caller is doing things in a sane order */
541 Assert(plansource->magic == CACHEDPLANSOURCE_MAGIC);
542 Assert(plansource->is_complete);
543 Assert(!plansource->is_saved);
544
545 /* This seems worth a real test, though */
546 if (plansource->is_oneshot)
547 elog(ERROR, "cannot save one-shot cached plan");
548
549 /*
550 * In typical use, this function would be called before generating any
551 * plans from the CachedPlanSource. If there is a generic plan, moving it
552 * into CacheMemoryContext would be pretty risky since it's unclear
553 * whether the caller has taken suitable care with making references
554 * long-lived. Best thing to do seems to be to discard the plan.
555 */
556 ReleaseGenericPlan(plansource);
557
558 /*
559 * Reparent the source memory context under CacheMemoryContext so that it
560 * will live indefinitely. The query_context follows along since it's
561 * already a child of the other one.
562 */
563 MemoryContextSetParent(plansource->context, CacheMemoryContext);
564
565 /*
566 * Add the entry to the global list of cached plans.
567 */
568 dlist_push_tail(&saved_plan_list, &plansource->node);
569
570 plansource->is_saved = true;
571 }
572
573 /*
574 * DropCachedPlan: destroy a cached plan.
575 *
576 * Actually this only destroys the CachedPlanSource: any referenced CachedPlan
577 * is released, but not destroyed until its refcount goes to zero. That
578 * handles the situation where DropCachedPlan is called while the plan is
579 * still in use.
580 */
581 void
582 DropCachedPlan(CachedPlanSource *plansource)
583 {
584 Assert(plansource->magic == CACHEDPLANSOURCE_MAGIC);
585
586 /* If it's been saved, remove it from the list */
587 if (plansource->is_saved)
588 {
589 dlist_delete(&plansource->node);
590 plansource->is_saved = false;
591 }
592
593 /* Decrement generic CachedPlan's refcount and drop if no longer needed */
594 ReleaseGenericPlan(plansource);
595
596 /* Mark it no longer valid */
597 plansource->magic = 0;
598
599 /*
600 * Remove the CachedPlanSource and all subsidiary data (including the
601 * query_context if any). But if it's a one-shot we can't free anything.
602 */
603 if (!plansource->is_oneshot)
604 MemoryContextDelete(plansource->context);
605 }
606
607 /*
608 * ReleaseGenericPlan: release a CachedPlanSource's generic plan, if any.
609 */
610 static void
611 ReleaseGenericPlan(CachedPlanSource *plansource)
612 {
613 /* Be paranoid about the possibility that ReleaseCachedPlan fails */
614 if (plansource->gplan)
615 {
616 CachedPlan *plan = plansource->gplan;
617
618 Assert(plan->magic == CACHEDPLAN_MAGIC);
619 plansource->gplan = NULL;
620 ReleaseCachedPlan(plan, NULL);
621 }
622 }
623
624 /*
625 * We must skip "overhead" operations that involve database access when the
626 * cached plan's subject statement is a transaction control command or one
627 * that requires a snapshot not to be set yet (such as SET or LOCK). More
628 * generally, statements that do not require parse analysis/rewrite/plan
629 * activity never need to be revalidated, so we can treat them all like that.
630 * For the convenience of postgres.c, treat empty statements that way too.
631 */
632 static bool
633 StmtPlanRequiresRevalidation(CachedPlanSource *plansource)
634 {
635 if (plansource->raw_parse_tree != NULL)
636 return stmt_requires_parse_analysis(plansource->raw_parse_tree);
637 else if (plansource->analyzed_parse_tree != NULL)
638 return query_requires_rewrite_plan(plansource->analyzed_parse_tree);
639 /* empty query never needs revalidation */
640 return false;
641 }
642
643 /*
644 * Determine if creating a plan for this CachedPlanSource requires a snapshot.
645 * In fact this function matches StmtPlanRequiresRevalidation(), but we want
646 * to preserve the distinction between stmt_requires_parse_analysis() and
647 * analyze_requires_snapshot().
648 */
649 static bool
650 BuildingPlanRequiresSnapshot(CachedPlanSource *plansource)
651 {
652 if (plansource->raw_parse_tree != NULL)
653 return analyze_requires_snapshot(plansource->raw_parse_tree);
654 else if (plansource->analyzed_parse_tree != NULL)
655 return query_requires_rewrite_plan(plansource->analyzed_parse_tree);
656 /* empty query never needs a snapshot */
657 return false;
658 }
659
660 /*
661 * RevalidateCachedQuery: ensure validity of analyzed-and-rewritten query tree.
662 *
663 * What we do here is re-acquire locks and redo parse analysis if necessary.
664 * On return, the query_list is valid and we have sufficient locks to begin
665 * planning.
666 *
667 * If any parse analysis activity is required, the caller's memory context is
668 * used for that work.
669 *
670 * The result value is the transient analyzed-and-rewritten query tree if we
671 * had to do re-analysis, and NIL otherwise. (This is returned just to save
672 * a tree copying step in a subsequent BuildCachedPlan call.)
673 */
674 static List *
675 RevalidateCachedQuery(CachedPlanSource *plansource,
676 QueryEnvironment *queryEnv)
677 {
678 bool snapshot_set;
679 List *tlist; /* transient query-tree list */
680 List *qlist; /* permanent query-tree list */
681 TupleDesc resultDesc;
682 MemoryContext querytree_context;
683 MemoryContext oldcxt;
684
685 /*
686 * For one-shot plans, we do not support revalidation checking; it's
687 * assumed the query is parsed, planned, and executed in one transaction,
688 * so that no lock re-acquisition is necessary. Also, if the statement
689 * type can't require revalidation, we needn't do anything (and we mustn't
690 * risk catalog accesses when handling, eg, transaction control commands).
691 */
692 if (plansource->is_oneshot || !StmtPlanRequiresRevalidation(plansource))
693 {
694 Assert(plansource->is_valid);
695 return NIL;
696 }
697
698 /*
699 * If the query is currently valid, we should have a saved search_path ---
700 * check to see if that matches the current environment. If not, we want
701 * to force replan. (We could almost ignore this consideration when
702 * working from an analyzed parse tree; but there are scenarios where
703 * planning can have search_path-dependent results, for example if it
704 * inlines an old-style SQL function.)
705 */
706 if (plansource->is_valid)
707 {
708 Assert(plansource->search_path != NULL);
709 if (!SearchPathMatchesCurrentEnvironment(plansource->search_path))
710 {
711 /* Invalidate the querytree and generic plan */
712 plansource->is_valid = false;
713 if (plansource->gplan)
714 plansource->gplan->is_valid = false;
715 }
716 }
717
718 /*
719 * If the query rewrite phase had a possible RLS dependency, we must redo
720 * it if either the role or the row_security setting has changed.
721 */
722 if (plansource->is_valid && plansource->dependsOnRLS &&
723 (plansource->rewriteRoleId != GetUserId() ||
724 plansource->rewriteRowSecurity != row_security))
725 plansource->is_valid = false;
726
727 /*
728 * If the query is currently valid, acquire locks on the referenced
729 * objects; then check again. We need to do it this way to cover the race
730 * condition that an invalidation message arrives before we get the locks.
731 */
732 if (plansource->is_valid)
733 {
734 AcquirePlannerLocks(plansource->query_list, true);
735
736 /*
737 * By now, if any invalidation has happened, the inval callback
738 * functions will have marked the query invalid.
739 */
740 if (plansource->is_valid)
741 {
742 /* Successfully revalidated and locked the query. */
743 return NIL;
744 }
745
746 /* Oops, the race case happened. Release useless locks. */
747 AcquirePlannerLocks(plansource->query_list, false);
748 }
749
750 /*
751 * Discard the no-longer-useful rewritten query tree. (Note: we don't
752 * want to do this any earlier, else we'd not have been able to release
753 * locks correctly in the race condition case.)
754 */
755 plansource->is_valid = false;
756 plansource->query_list = NIL;
757 plansource->relationOids = NIL;
758 plansource->invalItems = NIL;
759 plansource->search_path = NULL;
760
761 /*
762 * Free the query_context. We don't really expect MemoryContextDelete to
763 * fail, but just in case, make sure the CachedPlanSource is left in a
764 * reasonably sane state. (The generic plan won't get unlinked yet, but
765 * that's acceptable.)
766 */
767 if (plansource->query_context)
768 {
769 MemoryContext qcxt = plansource->query_context;
770
771 plansource->query_context = NULL;
772 MemoryContextDelete(qcxt);
773 }
774
775 /* Drop the generic plan reference if any */
776 ReleaseGenericPlan(plansource);
777
778 /*
779 * Now re-do parse analysis and rewrite. This not incidentally acquires
780 * the locks we need to do planning safely.
781 */
782 Assert(plansource->is_complete);
783
784 /*
785 * If a snapshot is already set (the normal case), we can just use that
786 * for parsing/planning. But if it isn't, install one. Note: no point in
787 * checking whether parse analysis requires a snapshot; utility commands
788 * don't have invalidatable plans, so we'd not get here for such a
789 * command.
790 */
791 snapshot_set = false;
792 if (!ActiveSnapshotSet())
793 {
794 PushActiveSnapshot(GetTransactionSnapshot());
795 snapshot_set = true;
796 }
797
798 /*
799 * Run parse analysis (if needed) and rule rewriting.
800 */
801 if (plansource->raw_parse_tree != NULL)
802 {
803 /* Source is raw parse tree */
804 RawStmt *rawtree;
805
806 /*
807 * The parser tends to scribble on its input, so we must copy the raw
808 * parse tree to prevent corruption of the cache.
809 */
810 rawtree = copyObject(plansource->raw_parse_tree);
811 if (plansource->parserSetup != NULL)
812 tlist = pg_analyze_and_rewrite_withcb(rawtree,
813 plansource->query_string,
814 plansource->parserSetup,
815 plansource->parserSetupArg,
816 queryEnv);
817 else
818 tlist = pg_analyze_and_rewrite_fixedparams(rawtree,
819 plansource->query_string,
820 plansource->param_types,
821 plansource->num_params,
822 queryEnv);
823 }
824 else if (plansource->analyzed_parse_tree != NULL)
825 {
826 /* Source is pre-analyzed query, so we only need to rewrite */
827 Query *analyzed_tree;
828
829 /* The rewriter scribbles on its input, too, so copy */
830 analyzed_tree = copyObject(plansource->analyzed_parse_tree);
831 /* Acquire locks needed before rewriting ... */
832 AcquireRewriteLocks(analyzed_tree, true, false);
833 /* ... and do it */
834 tlist = pg_rewrite_query(analyzed_tree);
835 }
836 else
837 {
838 /* Empty query, nothing to do */
839 tlist = NIL;
840 }
841
842 /* Apply post-rewrite callback if there is one */
843 if (plansource->postRewrite != NULL)
844 plansource->postRewrite(tlist, plansource->postRewriteArg);
845
846 /* Release snapshot if we got one */
847 if (snapshot_set)
848 PopActiveSnapshot();
849
850 /*
851 * Check or update the result tupdesc.
852 *
853 * We assume the parameter types didn't change from the first time, so no
854 * need to update that.
855 */
856 resultDesc = PlanCacheComputeResultDesc(tlist);
857 if (resultDesc == NULL && plansource->resultDesc == NULL)
858 {
859 /* OK, doesn't return tuples */
860 }
861 else if (resultDesc == NULL || plansource->resultDesc == NULL ||
862 !equalRowTypes(resultDesc, plansource->resultDesc))
863 {
864 /* can we give a better error message? */
865 if (plansource->fixed_result)
866 ereport(ERROR,
867 (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
868 errmsg("cached plan must not change result type")));
869 oldcxt = MemoryContextSwitchTo(plansource->context);
870 if (resultDesc)
871 resultDesc = CreateTupleDescCopy(resultDesc);
872 if (plansource->resultDesc)
873 FreeTupleDesc(plansource->resultDesc);
874 plansource->resultDesc = resultDesc;
875 MemoryContextSwitchTo(oldcxt);
876 }
877
878 /*
879 * Allocate new query_context and copy the completed querytree into it.
880 * It's transient until we complete the copying and dependency extraction.
881 */
882 querytree_context = AllocSetContextCreate(CurrentMemoryContext,
883 "CachedPlanQuery",
884 ALLOCSET_START_SMALL_SIZES);
885 oldcxt = MemoryContextSwitchTo(querytree_context);
886
887 qlist = copyObject(tlist);
888
889 /*
890 * Use the planner machinery to extract dependencies. Data is saved in
891 * query_context. (We assume that not a lot of extra cruft is created by
892 * this call.)
893 */
894 extract_query_dependencies((Node *) qlist,
895 &plansource->relationOids,
896 &plansource->invalItems,
897 &plansource->dependsOnRLS);
898
899 /* Update RLS info as well. */
900 plansource->rewriteRoleId = GetUserId();
901 plansource->rewriteRowSecurity = row_security;
902
903 /*
904 * Also save the current search_path in the query_context. (This should
905 * not generate much extra cruft either, since almost certainly the path
906 * is already valid.)
907 */
908 plansource->search_path = GetSearchPathMatcher(querytree_context);
909
910 MemoryContextSwitchTo(oldcxt);
911
912 /* Now reparent the finished query_context and save the links */
913 MemoryContextSetParent(querytree_context, plansource->context);
914
915 plansource->query_context = querytree_context;
916 plansource->query_list = qlist;
917
918 /*
919 * Note: we do not reset generic_cost or total_custom_cost, although we
920 * could choose to do so. If the DDL or statistics change that prompted
921 * the invalidation meant a significant change in the cost estimates, it
922 * would be better to reset those variables and start fresh; but often it
923 * doesn't, and we're better retaining our hard-won knowledge about the
924 * relative costs.
925 */
926
927 plansource->is_valid = true;
928
929 /* Return transient copy of querytrees for possible use in planning */
930 return tlist;
931 }
932
933 /*
934 * CheckCachedPlan: see if the CachedPlanSource's generic plan is valid.
935 *
936 * Caller must have already called RevalidateCachedQuery to verify that the
937 * querytree is up to date.
938 *
939 * On a "true" return, we have acquired the locks needed to run the plan.
940 * (We must do this for the "true" result to be race-condition-free.)
941 */
942 static bool
943 CheckCachedPlan(CachedPlanSource *plansource)
944 {
945 CachedPlan *plan = plansource->gplan;
946
947 /* Assert that caller checked the querytree */
948 Assert(plansource->is_valid);
949
950 /* If there's no generic plan, just say "false" */
951 if (!plan)
952 return false;
953
954 Assert(plan->magic == CACHEDPLAN_MAGIC);
955 /* Generic plans are never one-shot */
956 Assert(!plan->is_oneshot);
957
958 /*
959 * If plan isn't valid for current role, we can't use it.
960 */
961 if (plan->is_valid && plan->dependsOnRole &&
962 plan->planRoleId != GetUserId())
963 plan->is_valid = false;
964
965 /*
966 * If it appears valid, acquire locks and recheck; this is much the same
967 * logic as in RevalidateCachedQuery, but for a plan.
968 */
969 if (plan->is_valid)
970 {
971 /*
972 * Plan must have positive refcount because it is referenced by
973 * plansource; so no need to fear it disappears under us here.
974 */
975 Assert(plan->refcount > 0);
976
977 AcquireExecutorLocks(plan->stmt_list, true);
978
979 /*
980 * If plan was transient, check to see if TransactionXmin has
981 * advanced, and if so invalidate it.
982 */
983 if (plan->is_valid &&
984 TransactionIdIsValid(plan->saved_xmin) &&
985 !TransactionIdEquals(plan->saved_xmin, TransactionXmin))
986 plan->is_valid = false;
987
988 /*
989 * By now, if any invalidation has happened, the inval callback
990 * functions will have marked the plan invalid.
991 */
992 if (plan->is_valid)
993 {
994 /* Successfully revalidated and locked the query. */
995 return true;
996 }
997
998 /* Oops, the race case happened. Release useless locks. */
999 AcquireExecutorLocks(plan->stmt_list, false);
1000 }
1001
1002 /*
1003 * Plan has been invalidated, so unlink it from the parent and release it.
1004 */
1005 ReleaseGenericPlan(plansource);
1006
1007 return false;
1008 }
1009
1010 /*
1011 * BuildCachedPlan: construct a new CachedPlan from a CachedPlanSource.
1012 *
1013 * qlist should be the result value from a previous RevalidateCachedQuery,
1014 * or it can be set to NIL if we need to re-copy the plansource's query_list.
1015 *
1016 * To build a generic, parameter-value-independent plan, pass NULL for
1017 * boundParams. To build a custom plan, pass the actual parameter values via
1018 * boundParams. For best effect, the PARAM_FLAG_CONST flag should be set on
1019 * each parameter value; otherwise the planner will treat the value as a
1020 * hint rather than a hard constant.
1021 *
1022 * Planning work is done in the caller's memory context. The finished plan
1023 * is in a child memory context, which typically should get reparented
1024 * (unless this is a one-shot plan, in which case we don't copy the plan).
1025 */
1026 static CachedPlan *
1027 BuildCachedPlan(CachedPlanSource *plansource, List *qlist,
1028 ParamListInfo boundParams, QueryEnvironment *queryEnv)
1029 {
1030 CachedPlan *plan;
1031 List *plist;
1032 bool snapshot_set;
1033 bool is_transient;
1034 MemoryContext plan_context;
1035 MemoryContext oldcxt = CurrentMemoryContext;
1036 ListCell *lc;
1037
1038 /*
1039 * Normally the querytree should be valid already, but if it's not,
1040 * rebuild it.
1041 *
1042 * NOTE: GetCachedPlan should have called RevalidateCachedQuery first, so
1043 * we ought to be holding sufficient locks to prevent any invalidation.
1044 * However, if we're building a custom plan after having built and
1045 * rejected a generic plan, it's possible to reach here with is_valid
1046 * false due to an invalidation while making the generic plan. In theory
1047 * the invalidation must be a false positive, perhaps a consequence of an
1048 * sinval reset event or the debug_discard_caches code. But for safety,
1049 * let's treat it as real and redo the RevalidateCachedQuery call.
1050 */
1051 if (!plansource->is_valid)
1052 qlist = RevalidateCachedQuery(plansource, queryEnv);
1053
1054 /*
1055 * If we don't already have a copy of the querytree list that can be
1056 * scribbled on by the planner, make one. For a one-shot plan, we assume
1057 * it's okay to scribble on the original query_list.
1058 */
1059 if (qlist == NIL)
1060 {
1061 if (!plansource->is_oneshot)
1062 qlist = copyObject(plansource->query_list);
1063 else
1064 qlist = plansource->query_list;
1065 }
1066
1067 /*
1068 * If a snapshot is already set (the normal case), we can just use that
1069 * for planning. But if it isn't, and we need one, install one.
1070 */
1071 snapshot_set = false;
1072 if (!ActiveSnapshotSet() &&
1073 BuildingPlanRequiresSnapshot(plansource))
1074 {
1075 PushActiveSnapshot(GetTransactionSnapshot());
1076 snapshot_set = true;
1077 }
1078
1079 /*
1080 * Generate the plan.
1081 */
1082 plist = pg_plan_queries(qlist, plansource->query_string,
1083 plansource->cursor_options, boundParams);
1084
1085 /* Release snapshot if we got one */
1086 if (snapshot_set)
1087 PopActiveSnapshot();
1088
1089 /*
1090 * Normally we make a dedicated memory context for the CachedPlan and its
1091 * subsidiary data. (It's probably not going to be large, but just in
1092 * case, allow it to grow large. It's transient for the moment.) But for
1093 * a one-shot plan, we just leave it in the caller's memory context.
1094 */
1095 if (!plansource->is_oneshot)
1096 {
1097 plan_context = AllocSetContextCreate(CurrentMemoryContext,
1098 "CachedPlan",
1099 ALLOCSET_START_SMALL_SIZES);
1100 MemoryContextCopyAndSetIdentifier(plan_context, plansource->query_string);
1101
1102 /*
1103 * Copy plan into the new context.
1104 */
1105 MemoryContextSwitchTo(plan_context);
1106
1107 plist = copyObject(plist);
1108 }
1109 else
1110 plan_context = CurrentMemoryContext;
1111
1112 /*
1113 * Create and fill the CachedPlan struct within the new context.
1114 */
1115 plan = (CachedPlan *) palloc(sizeof(CachedPlan));
1116 plan->magic = CACHEDPLAN_MAGIC;
1117 plan->stmt_list = plist;
1118
1119 /*
1120 * CachedPlan is dependent on role either if RLS affected the rewrite
1121 * phase or if a role dependency was injected during planning. And it's
1122 * transient if any plan is marked so.
1123 */
1124 plan->planRoleId = GetUserId();
1125 plan->dependsOnRole = plansource->dependsOnRLS;
1126 is_transient = false;
1127 foreach(lc, plist)
1128 {
1129 PlannedStmt *plannedstmt = lfirst_node(PlannedStmt, lc);
1130
1131 if (plannedstmt->commandType == CMD_UTILITY)
1132 continue; /* Ignore utility statements */
1133
1134 if (plannedstmt->transientPlan)
1135 is_transient = true;
1136 if (plannedstmt->dependsOnRole)
1137 plan->dependsOnRole = true;
1138 }
1139 if (is_transient)
1140 {
1141 Assert(TransactionIdIsNormal(TransactionXmin));
1142 plan->saved_xmin = TransactionXmin;
1143 }
1144 else
1145 plan->saved_xmin = InvalidTransactionId;
1146 plan->refcount = 0;
1147 plan->context = plan_context;
1148 plan->is_oneshot = plansource->is_oneshot;
1149 plan->is_saved = false;
1150 plan->is_valid = true;
1151
1152 /* assign generation number to new plan */
1153 plan->generation = ++(plansource->generation);
1154
1155 MemoryContextSwitchTo(oldcxt);
1156
1157 return plan;
1158 }
1159
1160 /*
1161 * choose_custom_plan: choose whether to use custom or generic plan
1162 *
1163 * This defines the policy followed by GetCachedPlan.
1164 */
1165 static bool
1166 choose_custom_plan(CachedPlanSource *plansource, ParamListInfo boundParams)
1167 {
1168 double avg_custom_cost;
1169
1170 /* One-shot plans will always be considered custom */
1171 if (plansource->is_oneshot)
1172 return true;
1173
1174 /* Otherwise, never any point in a custom plan if there's no parameters */
1175 if (boundParams == NULL)
1176 return false;
1177 /* ... nor when planning would be a no-op */
1178 if (!StmtPlanRequiresRevalidation(plansource))
1179 return false;
1180
1181 /* Let settings force the decision */
1182 if (plan_cache_mode == PLAN_CACHE_MODE_FORCE_GENERIC_PLAN)
1183 return false;
1184 if (plan_cache_mode == PLAN_CACHE_MODE_FORCE_CUSTOM_PLAN)
1185 return true;
1186
1187 /* See if caller wants to force the decision */
1188 if (plansource->cursor_options & CURSOR_OPT_GENERIC_PLAN)
1189 return false;
1190 if (plansource->cursor_options & CURSOR_OPT_CUSTOM_PLAN)
1191 return true;
1192
1193 /* Generate custom plans until we have done at least 5 (arbitrary) */
1194 if (plansource->num_custom_plans < 5)
1195 return true;
1196
1197 avg_custom_cost = plansource->total_custom_cost / plansource->num_custom_plans;
1198
1199 /*
1200 * Prefer generic plan if it's less expensive than the average custom
1201 * plan. (Because we include a charge for cost of planning in the
1202 * custom-plan costs, this means the generic plan only has to be less
1203 * expensive than the execution cost plus replan cost of the custom
1204 * plans.)
1205 *
1206 * Note that if generic_cost is -1 (indicating we've not yet determined
1207 * the generic plan cost), we'll always prefer generic at this point.
1208 */
1209 if (plansource->generic_cost < avg_custom_cost)
1210 return false;
1211
1212 return true;
1213 }
1214
1215 /*
1216 * cached_plan_cost: calculate estimated cost of a plan
1217 *
1218 * If include_planner is true, also include the estimated cost of constructing
1219 * the plan. (We must factor that into the cost of using a custom plan, but
1220 * we don't count it for a generic plan.)
1221 */
1222 static double
1223 cached_plan_cost(CachedPlan *plan, bool include_planner)
1224 {
1225 double result = 0;
1226 ListCell *lc;
1227
1228 foreach(lc, plan->stmt_list)
1229 {
1230 PlannedStmt *plannedstmt = lfirst_node(PlannedStmt, lc);
1231
1232 if (plannedstmt->commandType == CMD_UTILITY)
1233 continue; /* Ignore utility statements */
1234
1235 result += plannedstmt->planTree->total_cost;
1236
1237 if (include_planner)
1238 {
1239 /*
1240 * Currently we use a very crude estimate of planning effort based
1241 * on the number of relations in the finished plan's rangetable.
1242 * Join planning effort actually scales much worse than linearly
1243 * in the number of relations --- but only until the join collapse
1244 * limits kick in. Also, while inheritance child relations surely
1245 * add to planning effort, they don't make the join situation
1246 * worse. So the actual shape of the planning cost curve versus
1247 * number of relations isn't all that obvious. It will take
1248 * considerable work to arrive at a less crude estimate, and for
1249 * now it's not clear that's worth doing.
1250 *
1251 * The other big difficulty here is that we don't have any very
1252 * good model of how planning cost compares to execution costs.
1253 * The current multiplier of 1000 * cpu_operator_cost is probably
1254 * on the low side, but we'll try this for awhile before making a
1255 * more aggressive correction.
1256 *
1257 * If we ever do write a more complicated estimator, it should
1258 * probably live in src/backend/optimizer/ not here.
1259 */
1260 int nrelations = list_length(plannedstmt->rtable);
1261
1262 result += 1000.0 * cpu_operator_cost * (nrelations + 1);
1263 }
1264 }
1265
1266 return result;
1267 }
1268
1269 /*
1270 * GetCachedPlan: get a cached plan from a CachedPlanSource.
1271 *
1272 * This function hides the logic that decides whether to use a generic
1273 * plan or a custom plan for the given parameters: the caller does not know
1274 * which it will get.
1275 *
1276 * On return, the plan is valid and we have sufficient locks to begin
1277 * execution.
1278 *
1279 * On return, the refcount of the plan has been incremented; a later
1280 * ReleaseCachedPlan() call is expected. If "owner" is not NULL then
1281 * the refcount has been reported to that ResourceOwner (note that this
1282 * is only supported for "saved" CachedPlanSources).
1283 *
1284 * Note: if any replanning activity is required, the caller's memory context
1285 * is used for that work.
1286 */
1287 CachedPlan *
1288 GetCachedPlan(CachedPlanSource *plansource, ParamListInfo boundParams,
1289 ResourceOwner owner, QueryEnvironment *queryEnv)
1290 {
1291 CachedPlan *plan = NULL;
1292 List *qlist;
1293 bool customplan;
1294
1295 /* Assert caller is doing things in a sane order */
1296 Assert(plansource->magic == CACHEDPLANSOURCE_MAGIC);
1297 Assert(plansource->is_complete);
1298 /* This seems worth a real test, though */
1299 if (owner && !plansource->is_saved)
1300 elog(ERROR, "cannot apply ResourceOwner to non-saved cached plan");
1301
1302 /* Make sure the querytree list is valid and we have parse-time locks */
1303 qlist = RevalidateCachedQuery(plansource, queryEnv);
1304
1305 /* Decide whether to use a custom plan */
1306 customplan = choose_custom_plan(plansource, boundParams);
1307
1308 if (!customplan)
1309 {
1310 if (CheckCachedPlan(plansource))
1311 {
1312 /* We want a generic plan, and we already have a valid one */
1313 plan = plansource->gplan;
1314 Assert(plan->magic == CACHEDPLAN_MAGIC);
1315 }
1316 else
1317 {
1318 /* Build a new generic plan */
1319 plan = BuildCachedPlan(plansource, qlist, NULL, queryEnv);
1320 /* Just make real sure plansource->gplan is clear */
1321 ReleaseGenericPlan(plansource);
1322 /* Link the new generic plan into the plansource */
1323 plansource->gplan = plan;
1324 plan->refcount++;
1325 /* Immediately reparent into appropriate context */
1326 if (plansource->is_saved)
1327 {
1328 /* saved plans all live under CacheMemoryContext */
1329 MemoryContextSetParent(plan->context, CacheMemoryContext);
1330 plan->is_saved = true;
1331 }
1332 else
1333 {
1334 /* otherwise, it should be a sibling of the plansource */
1335 MemoryContextSetParent(plan->context,
1336 MemoryContextGetParent(plansource->context));
1337 }
1338 /* Update generic_cost whenever we make a new generic plan */
1339 plansource->generic_cost = cached_plan_cost(plan, false);
1340
1341 /*
1342 * If, based on the now-known value of generic_cost, we'd not have
1343 * chosen to use a generic plan, then forget it and make a custom
1344 * plan. This is a bit of a wart but is necessary to avoid a
1345 * glitch in behavior when the custom plans are consistently big
1346 * winners; at some point we'll experiment with a generic plan and
1347 * find it's a loser, but we don't want to actually execute that
1348 * plan.
1349 */
1350 customplan = choose_custom_plan(plansource, boundParams);
1351
1352 /*
1353 * If we choose to plan again, we need to re-copy the query_list,
1354 * since the planner probably scribbled on it. We can force
1355 * BuildCachedPlan to do that by passing NIL.
1356 */
1357 qlist = NIL;
1358 }
1359 }
1360
1361 if (customplan)
1362 {
1363 /* Build a custom plan */
1364 plan = BuildCachedPlan(plansource, qlist, boundParams, queryEnv);
1365 /* Accumulate total costs of custom plans */
1366 plansource->total_custom_cost += cached_plan_cost(plan, true);
1367
1368 plansource->num_custom_plans++;
1369 }
1370 else
1371 {
1372 plansource->num_generic_plans++;
1373 }
1374
1375 Assert(plan != NULL);
1376
1377 /* Flag the plan as in use by caller */
1378 if (owner)
1379 ResourceOwnerEnlarge(owner);
1380 plan->refcount++;
1381 if (owner)
1382 ResourceOwnerRememberPlanCacheRef(owner, plan);
1383
1384 /*
1385 * Saved plans should be under CacheMemoryContext so they will not go away
1386 * until their reference count goes to zero. In the generic-plan cases we
1387 * already took care of that, but for a custom plan, do it as soon as we
1388 * have created a reference-counted link.
1389 */
1390 if (customplan && plansource->is_saved)
1391 {
1392 MemoryContextSetParent(plan->context, CacheMemoryContext);
1393 plan->is_saved = true;
1394 }
1395
1396 return plan;
1397 }
1398
1399 /*
1400 * ReleaseCachedPlan: release active use of a cached plan.
1401 *
1402 * This decrements the reference count, and frees the plan if the count
1403 * has thereby gone to zero. If "owner" is not NULL, it is assumed that
1404 * the reference count is managed by that ResourceOwner.
1405 *
1406 * Note: owner == NULL is used for releasing references that are in
1407 * persistent data structures, such as the parent CachedPlanSource or a
1408 * Portal. Transient references should be protected by a resource owner.
1409 */
1410 void
1411 ReleaseCachedPlan(CachedPlan *plan, ResourceOwner owner)
1412 {
1413 Assert(plan->magic == CACHEDPLAN_MAGIC);
1414 if (owner)
1415 {
1416 Assert(plan->is_saved);
1417 ResourceOwnerForgetPlanCacheRef(owner, plan);
1418 }
1419 Assert(plan->refcount > 0);
1420 plan->refcount--;
1421 if (plan->refcount == 0)
1422 {
1423 /* Mark it no longer valid */
1424 plan->magic = 0;
1425
1426 /* One-shot plans do not own their context, so we can't free them */
1427 if (!plan->is_oneshot)
1428 MemoryContextDelete(plan->context);
1429 }
1430 }
1431
1432 /*
1433 * CachedPlanAllowsSimpleValidityCheck: can we use CachedPlanIsSimplyValid?
1434 *
1435 * This function, together with CachedPlanIsSimplyValid, provides a fast path
1436 * for revalidating "simple" generic plans. The core requirement to be simple
1437 * is that the plan must not require taking any locks, which translates to
1438 * not touching any tables; this happens to match up well with an important
1439 * use-case in PL/pgSQL. This function tests whether that's true, along
1440 * with checking some other corner cases that we'd rather not bother with
1441 * handling in the fast path. (Note that it's still possible for such a plan
1442 * to be invalidated, for example due to a change in a function that was
1443 * inlined into the plan.)
1444 *
1445 * If the plan is simply valid, and "owner" is not NULL, record a refcount on
1446 * the plan in that resowner before returning. It is caller's responsibility
1447 * to be sure that a refcount is held on any plan that's being actively used.
1448 *
1449 * This must only be called on known-valid generic plans (eg, ones just
1450 * returned by GetCachedPlan). If it returns true, the caller may re-use
1451 * the cached plan as long as CachedPlanIsSimplyValid returns true; that
1452 * check is much cheaper than the full revalidation done by GetCachedPlan.
1453 * Nonetheless, no required checks are omitted.
1454 */
1455 bool
1456 CachedPlanAllowsSimpleValidityCheck(CachedPlanSource *plansource,
1457 CachedPlan *plan, ResourceOwner owner)
1458 {
1459 ListCell *lc;
1460
1461 /*
1462 * Sanity-check that the caller gave us a validated generic plan. Notice
1463 * that we *don't* assert plansource->is_valid as you might expect; that's
1464 * because it's possible that that's already false when GetCachedPlan
1465 * returns, e.g. because ResetPlanCache happened partway through. We
1466 * should accept the plan as long as plan->is_valid is true, and expect to
1467 * replan after the next CachedPlanIsSimplyValid call.
1468 */
1469 Assert(plansource->magic == CACHEDPLANSOURCE_MAGIC);
1470 Assert(plan->magic == CACHEDPLAN_MAGIC);
1471 Assert(plan->is_valid);
1472 Assert(plan == plansource->gplan);
1473 Assert(plansource->search_path != NULL);
1474 Assert(SearchPathMatchesCurrentEnvironment(plansource->search_path));
1475
1476 /* We don't support oneshot plans here. */
1477 if (plansource->is_oneshot)
1478 return false;
1479 Assert(!plan->is_oneshot);
1480
1481 /*
1482 * If the plan is dependent on RLS considerations, or it's transient,
1483 * reject. These things probably can't ever happen for table-free
1484 * queries, but for safety's sake let's check.
1485 */
1486 if (plansource->dependsOnRLS)
1487 return false;
1488 if (plan->dependsOnRole)
1489 return false;
1490 if (TransactionIdIsValid(plan->saved_xmin))
1491 return false;
1492
1493 /*
1494 * Reject if AcquirePlannerLocks would have anything to do. This is
1495 * simplistic, but there's no need to inquire any more carefully; indeed,
1496 * for current callers it shouldn't even be possible to hit any of these
1497 * checks.
1498 */
1499 foreach(lc, plansource->query_list)
1500 {
1501 Query *query = lfirst_node(Query, lc);
1502
1503 if (query->commandType == CMD_UTILITY)
1504 return false;
1505 if (query->rtable || query->cteList || query->hasSubLinks)
1506 return false;
1507 }
1508
1509 /*
1510 * Reject if AcquireExecutorLocks would have anything to do. This is
1511 * probably unnecessary given the previous check, but let's be safe.
1512 */
1513 foreach(lc, plan->stmt_list)
1514 {
1515 PlannedStmt *plannedstmt = lfirst_node(PlannedStmt, lc);
1516 ListCell *lc2;
1517
1518 if (plannedstmt->commandType == CMD_UTILITY)
1519 return false;
1520
1521 /*
1522 * We have to grovel through the rtable because it's likely to contain
1523 * an RTE_RESULT relation, rather than being totally empty.
1524 */
1525 foreach(lc2, plannedstmt->rtable)
1526 {
1527 RangeTblEntry *rte = (RangeTblEntry *) lfirst(lc2);
1528
1529 if (rte->rtekind == RTE_RELATION)
1530 return false;
1531 }
1532 }
1533
1534 /*
1535 * Okay, it's simple. Note that what we've primarily established here is
1536 * that no locks need be taken before checking the plan's is_valid flag.
1537 */
1538
1539 /* Bump refcount if requested. */
1540 if (owner)
1541 {
1542 ResourceOwnerEnlarge(owner);
1543 plan->refcount++;
1544 ResourceOwnerRememberPlanCacheRef(owner, plan);
1545 }
1546
1547 return true;
1548 }
1549
1550 /*
1551 * CachedPlanIsSimplyValid: quick check for plan still being valid
1552 *
1553 * This function must not be used unless CachedPlanAllowsSimpleValidityCheck
1554 * previously said it was OK.
1555 *
1556 * If the plan is valid, and "owner" is not NULL, record a refcount on
1557 * the plan in that resowner before returning. It is caller's responsibility
1558 * to be sure that a refcount is held on any plan that's being actively used.
1559 *
1560 * The code here is unconditionally safe as long as the only use of this
1561 * CachedPlanSource is in connection with the particular CachedPlan pointer
1562 * that's passed in. If the plansource were being used for other purposes,
1563 * it's possible that its generic plan could be invalidated and regenerated
1564 * while the current caller wasn't looking, and then there could be a chance
1565 * collision of address between this caller's now-stale plan pointer and the
1566 * actual address of the new generic plan. For current uses, that scenario
1567 * can't happen; but with a plansource shared across multiple uses, it'd be
1568 * advisable to also save plan->generation and verify that that still matches.
1569 */
1570 bool
1571 CachedPlanIsSimplyValid(CachedPlanSource *plansource, CachedPlan *plan,
1572 ResourceOwner owner)
1573 {
1574 /*
1575 * Careful here: since the caller doesn't necessarily hold a refcount on
1576 * the plan to start with, it's possible that "plan" is a dangling
1577 * pointer. Don't dereference it until we've verified that it still
1578 * matches the plansource's gplan (which is either valid or NULL).
1579 */
1580 Assert(plansource->magic == CACHEDPLANSOURCE_MAGIC);
1581
1582 /*
1583 * Has cache invalidation fired on this plan? We can check this right
1584 * away since there are no locks that we'd need to acquire first. Note
1585 * that here we *do* check plansource->is_valid, so as to force plan
1586 * rebuild if that's become false.
1587 */
1588 if (!plansource->is_valid ||
1589 plan == NULL || plan != plansource->gplan ||
1590 !plan->is_valid)
1591 return false;
1592
1593 Assert(plan->magic == CACHEDPLAN_MAGIC);
1594
1595 /* Is the search_path still the same as when we made it? */
1596 Assert(plansource->search_path != NULL);
1597 if (!SearchPathMatchesCurrentEnvironment(plansource->search_path))
1598 return false;
1599
1600 /* It's still good. Bump refcount if requested. */
1601 if (owner)
1602 {
1603 ResourceOwnerEnlarge(owner);
1604 plan->refcount++;
1605 ResourceOwnerRememberPlanCacheRef(owner, plan);
1606 }
1607
1608 return true;
1609 }
1610
1611 /*
1612 * CachedPlanSetParentContext: move a CachedPlanSource to a new memory context
1613 *
1614 * This can only be applied to unsaved plans; once saved, a plan always
1615 * lives underneath CacheMemoryContext.
1616 */
1617 void
1618 CachedPlanSetParentContext(CachedPlanSource *plansource,
1619 MemoryContext newcontext)
1620 {
1621 /* Assert caller is doing things in a sane order */
1622 Assert(plansource->magic == CACHEDPLANSOURCE_MAGIC);
1623 Assert(plansource->is_complete);
1624
1625 /* These seem worth real tests, though */
1626 if (plansource->is_saved)
1627 elog(ERROR, "cannot move a saved cached plan to another context");
1628 if (plansource->is_oneshot)
1629 elog(ERROR, "cannot move a one-shot cached plan to another context");
1630
1631 /* OK, let the caller keep the plan where he wishes */
1632 MemoryContextSetParent(plansource->context, newcontext);
1633
1634 /*
1635 * The query_context needs no special handling, since it's a child of
1636 * plansource->context. But if there's a generic plan, it should be
1637 * maintained as a sibling of plansource->context.
1638 */
1639 if (plansource->gplan)
1640 {
1641 Assert(plansource->gplan->magic == CACHEDPLAN_MAGIC);
1642 MemoryContextSetParent(plansource->gplan->context, newcontext);
1643 }
1644 }
1645
1646 /*
1647 * CopyCachedPlan: make a copy of a CachedPlanSource
1648 *
1649 * This is a convenience routine that does the equivalent of
1650 * CreateCachedPlan + CompleteCachedPlan, using the data stored in the
1651 * input CachedPlanSource. The result is therefore "unsaved" (regardless
1652 * of the state of the source), and we don't copy any generic plan either.
1653 * The result will be currently valid, or not, the same as the source.
1654 */
1655 CachedPlanSource *
1656 CopyCachedPlan(CachedPlanSource *plansource)
1657 {
1658 CachedPlanSource *newsource;
1659 MemoryContext source_context;
1660 MemoryContext querytree_context;
1661 MemoryContext oldcxt;
1662
1663 Assert(plansource->magic == CACHEDPLANSOURCE_MAGIC);
1664 Assert(plansource->is_complete);
1665
1666 /*
1667 * One-shot plans can't be copied, because we haven't taken care that
1668 * parsing/planning didn't scribble on the raw parse tree or querytrees.
1669 */
1670 if (plansource->is_oneshot)
1671 elog(ERROR, "cannot copy a one-shot cached plan");
1672
1673 source_context = AllocSetContextCreate(CurrentMemoryContext,
1674 "CachedPlanSource",
1675 ALLOCSET_START_SMALL_SIZES);
1676
1677 oldcxt = MemoryContextSwitchTo(source_context);
1678
1679 newsource = (CachedPlanSource *) palloc0(sizeof(CachedPlanSource));
1680 newsource->magic = CACHEDPLANSOURCE_MAGIC;
1681 newsource->raw_parse_tree = copyObject(plansource->raw_parse_tree);
1682 newsource->analyzed_parse_tree = copyObject(plansource->analyzed_parse_tree);
1683 newsource->query_string = pstrdup(plansource->query_string);
1684 MemoryContextSetIdentifier(source_context, newsource->query_string);
1685 newsource->commandTag = plansource->commandTag;
1686 if (plansource->num_params > 0)
1687 {
1688 newsource->param_types = (Oid *)
1689 palloc(plansource->num_params * sizeof(Oid));
1690 memcpy(newsource->param_types, plansource->param_types,
1691 plansource->num_params * sizeof(Oid));
1692 }
1693 else
1694 newsource->param_types = NULL;
1695 newsource->num_params = plansource->num_params;
1696 newsource->parserSetup = plansource->parserSetup;
1697 newsource->parserSetupArg = plansource->parserSetupArg;
1698 newsource->postRewrite = plansource->postRewrite;
1699 newsource->postRewriteArg = plansource->postRewriteArg;
1700 newsource->cursor_options = plansource->cursor_options;
1701 newsource->fixed_result = plansource->fixed_result;
1702 if (plansource->resultDesc)
1703 newsource->resultDesc = CreateTupleDescCopy(plansource->resultDesc);
1704 else
1705 newsource->resultDesc = NULL;
1706 newsource->context = source_context;
1707
1708 querytree_context = AllocSetContextCreate(source_context,
1709 "CachedPlanQuery",
1710 ALLOCSET_START_SMALL_SIZES);
1711 MemoryContextSwitchTo(querytree_context);
1712 newsource->query_list = copyObject(plansource->query_list);
1713 newsource->relationOids = copyObject(plansource->relationOids);
1714 newsource->invalItems = copyObject(plansource->invalItems);
1715 if (plansource->search_path)
1716 newsource->search_path = CopySearchPathMatcher(plansource->search_path);
1717 newsource->query_context = querytree_context;
1718 newsource->rewriteRoleId = plansource->rewriteRoleId;
1719 newsource->rewriteRowSecurity = plansource->rewriteRowSecurity;
1720 newsource->dependsOnRLS = plansource->dependsOnRLS;
1721
1722 newsource->gplan = NULL;
1723
1724 newsource->is_oneshot = false;
1725 newsource->is_complete = true;
1726 newsource->is_saved = false;
1727 newsource->is_valid = plansource->is_valid;
1728 newsource->generation = plansource->generation;
1729
1730 /* We may as well copy any acquired cost knowledge */
1731 newsource->generic_cost = plansource->generic_cost;
1732 newsource->total_custom_cost = plansource->total_custom_cost;
1733 newsource->num_generic_plans = plansource->num_generic_plans;
1734 newsource->num_custom_plans = plansource->num_custom_plans;
1735
1736 MemoryContextSwitchTo(oldcxt);
1737
1738 return newsource;
1739 }
1740
1741 /*
1742 * CachedPlanIsValid: test whether the rewritten querytree within a
1743 * CachedPlanSource is currently valid (that is, not marked as being in need
1744 * of revalidation).
1745 *
1746 * This result is only trustworthy (ie, free from race conditions) if
1747 * the caller has acquired locks on all the relations used in the plan.
1748 */
1749 bool
1750 CachedPlanIsValid(CachedPlanSource *plansource)
1751 {
1752 Assert(plansource->magic == CACHEDPLANSOURCE_MAGIC);
1753 return plansource->is_valid;
1754 }
1755
1756 /*
1757 * CachedPlanGetTargetList: return tlist, if any, describing plan's output
1758 *
1759 * The result is guaranteed up-to-date. However, it is local storage
1760 * within the cached plan, and may disappear next time the plan is updated.
1761 */
1762 List *
1763 CachedPlanGetTargetList(CachedPlanSource *plansource,
1764 QueryEnvironment *queryEnv)
1765 {
1766 Query *pstmt;
1767
1768 /* Assert caller is doing things in a sane order */
1769 Assert(plansource->magic == CACHEDPLANSOURCE_MAGIC);
1770 Assert(plansource->is_complete);
1771
1772 /*
1773 * No work needed if statement doesn't return tuples (we assume this
1774 * feature cannot be changed by an invalidation)
1775 */
1776 if (plansource->resultDesc == NULL)
1777 return NIL;
1778
1779 /* Make sure the querytree list is valid and we have parse-time locks */
1780 RevalidateCachedQuery(plansource, queryEnv);
1781
1782 /* Get the primary statement and find out what it returns */
1783 pstmt = QueryListGetPrimaryStmt(plansource->query_list);
1784
1785 return FetchStatementTargetList((Node *) pstmt);
1786 }
1787
1788 /*
1789 * GetCachedExpression: construct a CachedExpression for an expression.
1790 *
1791 * This performs the same transformations on the expression as
1792 * expression_planner(), ie, convert an expression as emitted by parse
1793 * analysis to be ready to pass to the executor.
1794 *
1795 * The result is stashed in a private, long-lived memory context.
1796 * (Note that this might leak a good deal of memory in the caller's
1797 * context before that.) The passed-in expr tree is not modified.
1798 */
1799 CachedExpression *
1800 GetCachedExpression(Node *expr)
1801 {
1802 CachedExpression *cexpr;
1803 List *relationOids;
1804 List *invalItems;
1805 MemoryContext cexpr_context;
1806 MemoryContext oldcxt;
1807
1808 /*
1809 * Pass the expression through the planner, and collect dependencies.
1810 * Everything built here is leaked in the caller's context; that's
1811 * intentional to minimize the size of the permanent data structure.
1812 */
1813 expr = (Node *) expression_planner_with_deps((Expr *) expr,
1814 &relationOids,
1815 &invalItems);
1816
1817 /*
1818 * Make a private memory context, and copy what we need into that. To
1819 * avoid leaking a long-lived context if we fail while copying data, we
1820 * initially make the context under the caller's context.
1821 */
1822 cexpr_context = AllocSetContextCreate(CurrentMemoryContext,
1823 "CachedExpression",
1824 ALLOCSET_SMALL_SIZES);
1825
1826 oldcxt = MemoryContextSwitchTo(cexpr_context);
1827
1828 cexpr = (CachedExpression *) palloc(sizeof(CachedExpression));
1829 cexpr->magic = CACHEDEXPR_MAGIC;
1830 cexpr->expr = copyObject(expr);
1831 cexpr->is_valid = true;
1832 cexpr->relationOids = copyObject(relationOids);
1833 cexpr->invalItems = copyObject(invalItems);
1834 cexpr->context = cexpr_context;
1835
1836 MemoryContextSwitchTo(oldcxt);
1837
1838 /*
1839 * Reparent the expr's memory context under CacheMemoryContext so that it
1840 * will live indefinitely.
1841 */
1842 MemoryContextSetParent(cexpr_context, CacheMemoryContext);
1843
1844 /*
1845 * Add the entry to the global list of cached expressions.
1846 */
1847 dlist_push_tail(&cached_expression_list, &cexpr->node);
1848
1849 return cexpr;
1850 }
1851
1852 /*
1853 * FreeCachedExpression
1854 * Delete a CachedExpression.
1855 */
1856 void
1857 FreeCachedExpression(CachedExpression *cexpr)
1858 {
1859 /* Sanity check */
1860 Assert(cexpr->magic == CACHEDEXPR_MAGIC);
1861 /* Unlink from global list */
1862 dlist_delete(&cexpr->node);
1863 /* Free all storage associated with CachedExpression */
1864 MemoryContextDelete(cexpr->context);
1865 }
1866
1867 /*
1868 * QueryListGetPrimaryStmt
1869 * Get the "primary" stmt within a list, ie, the one marked canSetTag.
1870 *
1871 * Returns NULL if no such stmt. If multiple queries within the list are
1872 * marked canSetTag, returns the first one. Neither of these cases should
1873 * occur in present usages of this function.
1874 */
1875 static Query *
1876 QueryListGetPrimaryStmt(List *stmts)
1877 {
1878 ListCell *lc;
1879
1880 foreach(lc, stmts)
1881 {
1882 Query *stmt = lfirst_node(Query, lc);
1883
1884 if (stmt->canSetTag)
1885 return stmt;
1886 }
1887 return NULL;
1888 }
1889
1890 /*
1891 * AcquireExecutorLocks: acquire locks needed for execution of a cached plan;
1892 * or release them if acquire is false.
1893 */
1894 static void
1895 AcquireExecutorLocks(List *stmt_list, bool acquire)
1896 {
1897 ListCell *lc1;
1898
1899 foreach(lc1, stmt_list)
1900 {
1901 PlannedStmt *plannedstmt = lfirst_node(PlannedStmt, lc1);
1902 ListCell *lc2;
1903
1904 if (plannedstmt->commandType == CMD_UTILITY)
1905 {
1906 /*
1907 * Ignore utility statements, except those (such as EXPLAIN) that
1908 * contain a parsed-but-not-planned query. Note: it's okay to use
1909 * ScanQueryForLocks, even though the query hasn't been through
1910 * rule rewriting, because rewriting doesn't change the query
1911 * representation.
1912 */
1913 Query *query = UtilityContainsQuery(plannedstmt->utilityStmt);
1914
1915 if (query)
1916 ScanQueryForLocks(query, acquire);
1917 continue;
1918 }
1919
1920 foreach(lc2, plannedstmt->rtable)
1921 {
1922 RangeTblEntry *rte = (RangeTblEntry *) lfirst(lc2);
1923
1924 if (!(rte->rtekind == RTE_RELATION ||
1925 (rte->rtekind == RTE_SUBQUERY && OidIsValid(rte->relid))))
1926 continue;
1927
1928 /*
1929 * Acquire the appropriate type of lock on each relation OID. Note
1930 * that we don't actually try to open the rel, and hence will not
1931 * fail if it's been dropped entirely --- we'll just transiently
1932 * acquire a non-conflicting lock.
1933 */
1934 if (acquire)
1935 LockRelationOid(rte->relid, rte->rellockmode);
1936 else
1937 UnlockRelationOid(rte->relid, rte->rellockmode);
1938 }
1939 }
1940 }
1941
1942 /*
1943 * AcquirePlannerLocks: acquire locks needed for planning of a querytree list;
1944 * or release them if acquire is false.
1945 *
1946 * Note that we don't actually try to open the relations, and hence will not
1947 * fail if one has been dropped entirely --- we'll just transiently acquire
1948 * a non-conflicting lock.
1949 */
1950 static void
1951 AcquirePlannerLocks(List *stmt_list, bool acquire)
1952 {
1953 ListCell *lc;
1954
1955 foreach(lc, stmt_list)
1956 {
1957 Query *query = lfirst_node(Query, lc);
1958
1959 if (query->commandType == CMD_UTILITY)
1960 {
1961 /* Ignore utility statements, unless they contain a Query */
1962 query = UtilityContainsQuery(query->utilityStmt);
1963 if (query)
1964 ScanQueryForLocks(query, acquire);
1965 continue;
1966 }
1967
1968 ScanQueryForLocks(query, acquire);
1969 }
1970 }
1971
1972 /*
1973 * ScanQueryForLocks: recursively scan one Query for AcquirePlannerLocks.
1974 */
1975 static void
1976 ScanQueryForLocks(Query *parsetree, bool acquire)
1977 {
1978 ListCell *lc;
1979
1980 /* Shouldn't get called on utility commands */
1981 Assert(parsetree->commandType != CMD_UTILITY);
1982
1983 /*
1984 * First, process RTEs of the current query level.
1985 */
1986 foreach(lc, parsetree->rtable)
1987 {
1988 RangeTblEntry *rte = (RangeTblEntry *) lfirst(lc);
1989
1990 switch (rte->rtekind)
1991 {
1992 case RTE_RELATION:
1993 /* Acquire or release the appropriate type of lock */
1994 if (acquire)
1995 LockRelationOid(rte->relid, rte->rellockmode);
1996 else
1997 UnlockRelationOid(rte->relid, rte->rellockmode);
1998 break;
1999
2000 case RTE_SUBQUERY:
2001 /* If this was a view, must lock/unlock the view */
2002 if (OidIsValid(rte->relid))
2003 {
2004 if (acquire)
2005 LockRelationOid(rte->relid, rte->rellockmode);
2006 else
2007 UnlockRelationOid(rte->relid, rte->rellockmode);
2008 }
2009 /* Recurse into subquery-in-FROM */
2010 ScanQueryForLocks(rte->subquery, acquire);
2011 break;
2012
2013 default:
2014 /* ignore other types of RTEs */
2015 break;
2016 }
2017 }
2018
2019 /* Recurse into subquery-in-WITH */
2020 foreach(lc, parsetree->cteList)
2021 {
2022 CommonTableExpr *cte = lfirst_node(CommonTableExpr, lc);
2023
2024 ScanQueryForLocks(castNode(Query, cte->ctequery), acquire);
2025 }
2026
2027 /*
2028 * Recurse into sublink subqueries, too. But we already did the ones in
2029 * the rtable and cteList.
2030 */
2031 if (parsetree->hasSubLinks)
2032 {
2033 query_tree_walker(parsetree, ScanQueryWalker, &acquire,
2034 QTW_IGNORE_RC_SUBQUERIES);
2035 }
2036 }
2037
2038 /*
2039 * Walker to find sublink subqueries for ScanQueryForLocks
2040 */
2041 static bool
2042 ScanQueryWalker(Node *node, bool *acquire)
2043 {
2044 if (node == NULL)
2045 return false;
2046 if (IsA(node, SubLink))
2047 {
2048 SubLink *sub = (SubLink *) node;
2049
2050 /* Do what we came for */
2051 ScanQueryForLocks(castNode(Query, sub->subselect), *acquire);
2052 /* Fall through to process lefthand args of SubLink */
2053 }
2054
2055 /*
2056 * Do NOT recurse into Query nodes, because ScanQueryForLocks already
2057 * processed subselects of subselects for us.
2058 */
2059 return expression_tree_walker(node, ScanQueryWalker, acquire);
2060 }
2061
2062 /*
2063 * PlanCacheComputeResultDesc: given a list of analyzed-and-rewritten Queries,
2064 * determine the result tupledesc it will produce. Returns NULL if the
2065 * execution will not return tuples.
2066 *
2067 * Note: the result is created or copied into current memory context.
2068 */
2069 static TupleDesc
2070 PlanCacheComputeResultDesc(List *stmt_list)
2071 {
2072 Query *query;
2073
2074 switch (ChoosePortalStrategy(stmt_list))
2075 {
2076 case PORTAL_ONE_SELECT:
2077 case PORTAL_ONE_MOD_WITH:
2078 query = linitial_node(Query, stmt_list);
2079 return ExecCleanTypeFromTL(query->targetList);
2080
2081 case PORTAL_ONE_RETURNING:
2082 query = QueryListGetPrimaryStmt(stmt_list);
2083 Assert(query->returningList);
2084 return ExecCleanTypeFromTL(query->returningList);
2085
2086 case PORTAL_UTIL_SELECT:
2087 query = linitial_node(Query, stmt_list);
2088 Assert(query->utilityStmt);
2089 return UtilityTupleDescriptor(query->utilityStmt);
2090
2091 case PORTAL_MULTI_QUERY:
2092 /* will not return tuples */
2093 break;
2094 }
2095 return NULL;
2096 }
2097
2098 /*
2099 * PlanCacheRelCallback
2100 * Relcache inval callback function
2101 *
2102 * Invalidate all plans mentioning the given rel, or all plans mentioning
2103 * any rel at all if relid == InvalidOid.
2104 */
2105 static void
2106 PlanCacheRelCallback(Datum arg, Oid relid)
2107 {
2108 dlist_iter iter;
2109
2110 dlist_foreach(iter, &saved_plan_list)
2111 {
2112 CachedPlanSource *plansource = dlist_container(CachedPlanSource,
2113 node, iter.cur);
2114
2115 Assert(plansource->magic == CACHEDPLANSOURCE_MAGIC);
2116
2117 /* No work if it's already invalidated */
2118 if (!plansource->is_valid)
2119 continue;
2120
2121 /* Never invalidate if parse/plan would be a no-op anyway */
2122 if (!StmtPlanRequiresRevalidation(plansource))
2123 continue;
2124
2125 /*
2126 * Check the dependency list for the rewritten querytree.
2127 */
2128 if ((relid == InvalidOid) ? plansource->relationOids != NIL :
2129 list_member_oid(plansource->relationOids, relid))
2130 {
2131 /* Invalidate the querytree and generic plan */
2132 plansource->is_valid = false;
2133 if (plansource->gplan)
2134 plansource->gplan->is_valid = false;
2135 }
2136
2137 /*
2138 * The generic plan, if any, could have more dependencies than the
2139 * querytree does, so we have to check it too.
2140 */
2141 if (plansource->gplan && plansource->gplan->is_valid)
2142 {
2143 ListCell *lc;
2144
2145 foreach(lc, plansource->gplan->stmt_list)
2146 {
2147 PlannedStmt *plannedstmt = lfirst_node(PlannedStmt, lc);
2148
2149 if (plannedstmt->commandType == CMD_UTILITY)
2150 continue; /* Ignore utility statements */
2151 if ((relid == InvalidOid) ? plannedstmt->relationOids != NIL :
2152 list_member_oid(plannedstmt->relationOids, relid))
2153 {
2154 /* Invalidate the generic plan only */
2155 plansource->gplan->is_valid = false;
2156 break; /* out of stmt_list scan */
2157 }
2158 }
2159 }
2160 }
2161
2162 /* Likewise check cached expressions */
2163 dlist_foreach(iter, &cached_expression_list)
2164 {
2165 CachedExpression *cexpr = dlist_container(CachedExpression,
2166 node, iter.cur);
2167
2168 Assert(cexpr->magic == CACHEDEXPR_MAGIC);
2169
2170 /* No work if it's already invalidated */
2171 if (!cexpr->is_valid)
2172 continue;
2173
2174 if ((relid == InvalidOid) ? cexpr->relationOids != NIL :
2175 list_member_oid(cexpr->relationOids, relid))
2176 {
2177 cexpr->is_valid = false;
2178 }
2179 }
2180 }
2181
2182 /*
2183 * PlanCacheObjectCallback
2184 * Syscache inval callback function for PROCOID and TYPEOID caches
2185 *
2186 * Invalidate all plans mentioning the object with the specified hash value,
2187 * or all plans mentioning any member of this cache if hashvalue == 0.
2188 */
2189 static void
2190 PlanCacheObjectCallback(Datum arg, int cacheid, uint32 hashvalue)
2191 {
2192 dlist_iter iter;
2193
2194 dlist_foreach(iter, &saved_plan_list)
2195 {
2196 CachedPlanSource *plansource = dlist_container(CachedPlanSource,
2197 node, iter.cur);
2198 ListCell *lc;
2199
2200 Assert(plansource->magic == CACHEDPLANSOURCE_MAGIC);
2201
2202 /* No work if it's already invalidated */
2203 if (!plansource->is_valid)
2204 continue;
2205
2206 /* Never invalidate if parse/plan would be a no-op anyway */
2207 if (!StmtPlanRequiresRevalidation(plansource))
2208 continue;
2209
2210 /*
2211 * Check the dependency list for the rewritten querytree.
2212 */
2213 foreach(lc, plansource->invalItems)
2214 {
2215 PlanInvalItem *item = (PlanInvalItem *) lfirst(lc);
2216
2217 if (item->cacheId != cacheid)
2218 continue;
2219 if (hashvalue == 0 ||
2220 item->hashValue == hashvalue)
2221 {
2222 /* Invalidate the querytree and generic plan */
2223 plansource->is_valid = false;
2224 if (plansource->gplan)
2225 plansource->gplan->is_valid = false;
2226 break;
2227 }
2228 }
2229
2230 /*
2231 * The generic plan, if any, could have more dependencies than the
2232 * querytree does, so we have to check it too.
2233 */
2234 if (plansource->gplan && plansource->gplan->is_valid)
2235 {
2236 foreach(lc, plansource->gplan->stmt_list)
2237 {
2238 PlannedStmt *plannedstmt = lfirst_node(PlannedStmt, lc);
2239 ListCell *lc3;
2240
2241 if (plannedstmt->commandType == CMD_UTILITY)
2242 continue; /* Ignore utility statements */
2243 foreach(lc3, plannedstmt->invalItems)
2244 {
2245 PlanInvalItem *item = (PlanInvalItem *) lfirst(lc3);
2246
2247 if (item->cacheId != cacheid)
2248 continue;
2249 if (hashvalue == 0 ||
2250 item->hashValue == hashvalue)
2251 {
2252 /* Invalidate the generic plan only */
2253 plansource->gplan->is_valid = false;
2254 break; /* out of invalItems scan */
2255 }
2256 }
2257 if (!plansource->gplan->is_valid)
2258 break; /* out of stmt_list scan */
2259 }
2260 }
2261 }
2262
2263 /* Likewise check cached expressions */
2264 dlist_foreach(iter, &cached_expression_list)
2265 {
2266 CachedExpression *cexpr = dlist_container(CachedExpression,
2267 node, iter.cur);
2268 ListCell *lc;
2269
2270 Assert(cexpr->magic == CACHEDEXPR_MAGIC);
2271
2272 /* No work if it's already invalidated */
2273 if (!cexpr->is_valid)
2274 continue;
2275
2276 foreach(lc, cexpr->invalItems)
2277 {
2278 PlanInvalItem *item = (PlanInvalItem *) lfirst(lc);
2279
2280 if (item->cacheId != cacheid)
2281 continue;
2282 if (hashvalue == 0 ||
2283 item->hashValue == hashvalue)
2284 {
2285 cexpr->is_valid = false;
2286 break;
2287 }
2288 }
2289 }
2290 }
2291
2292 /*
2293 * PlanCacheRoleCallback
2294 * Syscache inval callback function for AUTHMEMROLEMEM, AUTHOID, and
2295 * DATABASEOID caches
2296 *
2297 * Role membership, role attributes, and database ownership (which confers
2298 * membership in pg_database_owner) affect planning by way of row-level
2299 * security, so invalidate just the role-dependent plans. For DATABASEOID, we
2300 * can ignore changes to other databases' pg_database rows.
2301 */
2302 static void
2303 PlanCacheRoleCallback(Datum arg, int cacheid, uint32 hashvalue)
2304 {
2305 dlist_iter iter;
2306
2307 if (cacheid == DATABASEOID &&
2308 hashvalue != cached_db_hash &&
2309 hashvalue != 0)
2310 return; /* ignore pg_database changes for other DBs */
2311
2312 dlist_foreach(iter, &saved_plan_list)
2313 {
2314 CachedPlanSource *plansource = dlist_container(CachedPlanSource,
2315 node, iter.cur);
2316
2317 Assert(plansource->magic == CACHEDPLANSOURCE_MAGIC);
2318
2319 /* No work if it's already invalidated */
2320 if (!plansource->is_valid)
2321 continue;
2322
2323 /* Never invalidate if parse/plan would be a no-op anyway */
2324 if (!StmtPlanRequiresRevalidation(plansource))
2325 continue;
2326
2327 if (plansource->dependsOnRLS)
2328 {
2329 /* Invalidate the querytree and generic plan */
2330 plansource->is_valid = false;
2331 if (plansource->gplan)
2332 plansource->gplan->is_valid = false;
2333 }
2334 else if (plansource->gplan && plansource->gplan->dependsOnRole)
2335 {
2336 /* Invalidate the generic plan only */
2337 plansource->gplan->is_valid = false;
2338 }
2339 }
2340 }
2341
2342 /*
2343 * PlanCacheSysCallback
2344 * Syscache inval callback function for other caches
2345 *
2346 * Just invalidate everything...
2347 */
2348 static void
2349 PlanCacheSysCallback(Datum arg, int cacheid, uint32 hashvalue)
2350 {
2351 ResetPlanCache();
2352 }
2353
2354 /*
2355 * ResetPlanCache: invalidate all cached plans.
2356 */
2357 void
2358 ResetPlanCache(void)
2359 {
2360 dlist_iter iter;
2361
2362 dlist_foreach(iter, &saved_plan_list)
2363 {
2364 CachedPlanSource *plansource = dlist_container(CachedPlanSource,
2365 node, iter.cur);
2366
2367 Assert(plansource->magic == CACHEDPLANSOURCE_MAGIC);
2368
2369 /* No work if it's already invalidated */
2370 if (!plansource->is_valid)
2371 continue;
2372
2373 /*
2374 * We *must not* mark transaction control statements as invalid,
2375 * particularly not ROLLBACK, because they may need to be executed in
2376 * aborted transactions when we can't revalidate them (cf bug #5269).
2377 * In general there's no point in invalidating statements for which a
2378 * new parse analysis/rewrite/plan cycle would certainly give the same
2379 * results.
2380 */
2381 if (!StmtPlanRequiresRevalidation(plansource))
2382 continue;
2383
2384 plansource->is_valid = false;
2385 if (plansource->gplan)
2386 plansource->gplan->is_valid = false;
2387 }
2388
2389 /* Likewise invalidate cached expressions */
2390 dlist_foreach(iter, &cached_expression_list)
2391 {
2392 CachedExpression *cexpr = dlist_container(CachedExpression,
2393 node, iter.cur);
2394
2395 Assert(cexpr->magic == CACHEDEXPR_MAGIC);
2396
2397 cexpr->is_valid = false;
2398 }
2399 }
2400
2401 /*
2402 * Release all CachedPlans remembered by 'owner'
2403 */
2404 void
2405 ReleaseAllPlanCacheRefsInOwner(ResourceOwner owner)
2406 {
2407 ResourceOwnerReleaseAllOfKind(owner, &planref_resowner_desc);
2408 }
2409
2410 /* ResourceOwner callbacks */
2411
2412 static void
2413 ResOwnerReleaseCachedPlan(Datum res)
2414 {
2415 ReleaseCachedPlan((CachedPlan *) DatumGetPointer(res), NULL);
2416 }