#include "postgres.h"
#include "pg_plan_advice.h"
#include "pgpa_ast.h"
#include "pgpa_identifier.h"
#include "pgpa_output.h"
#include "pgpa_planner.h"
#include "pgpa_trove.h"
#include "pgpa_walker.h"
#include "commands/defrem.h"
#include "commands/explain.h"
#include "commands/explain_format.h"
#include "commands/explain_state.h"
#include "funcapi.h"
#include "optimizer/planner.h"
#include "storage/dsm_registry.h"
#include "utils/guc.h"

Include dependency graph for pg_plan_advice.c:

Functions
static void	pg_plan_advice_explain_option_handler (ExplainState es, DefElem opt, ParseState *pstate)

static void	pg_plan_advice_explain_per_plan_hook (PlannedStmt plannedstmt, IntoClause into, ExplainState es, const char queryString, ParamListInfo params, QueryEnvironment *queryEnv)

static bool	pg_plan_advice_advice_check_hook (char newval, void extra, GucSource source)

static DefElem *	find_defelem_by_defname (List deflist, char defname)

void	_PG_init (void)

MemoryContext	pg_plan_advice_get_mcxt (void)

bool	pg_plan_advice_should_explain (ExplainState *es)

char *	pg_plan_advice_get_supplied_query_advice (PlannerGlobal glob, Query parse, const char query_string, int cursorOptions, ExplainState es)

void	pg_plan_advice_add_advisor (pg_plan_advice_advisor_hook hook)

void	pg_plan_advice_remove_advisor (pg_plan_advice_advisor_hook hook)

void	pg_plan_advice_request_advice_generation (bool activate)

static void	pg_plan_advice_explain_text_multiline (ExplainState es, char qlabel, char *value)

static void	pg_plan_advice_explain_feedback (ExplainState es, List feedback)

Function Documentation

◆ _PG_init()

void _PG_init ( void )

Definition at line 65 of file pg_plan_advice.c.

{
    DefineCustomStringVariable("pg_plan_advice.advice",
                               "advice to apply during query planning",
                               NULL,
                               &pg_plan_advice_advice,
                               NULL,
                               PGC_USERSET,
                               0,
                               pg_plan_advice_advice_check_hook,
                               NULL,
                               NULL);
 
    DefineCustomBoolVariable("pg_plan_advice.always_explain_supplied_advice",
                             "EXPLAIN output includes supplied advice even without EXPLAIN (PLAN_ADVICE)",
                             NULL,
                             &pg_plan_advice_always_explain_supplied_advice,
                             true,
                             PGC_USERSET,
                             0,
                             NULL,
                             NULL,
                             NULL);
 
    DefineCustomBoolVariable("pg_plan_advice.always_store_advice_details",
                             "Generate advice strings even when seemingly not required",
                             "Use this option to see generated advice for prepared queries.",
                             &pg_plan_advice_always_store_advice_details,
                             false,
                             PGC_USERSET,
                             0,
                             NULL,
                             NULL,
                             NULL);
 
    DefineCustomBoolVariable("pg_plan_advice.feedback_warnings",
                             "Warn when supplied advice does not apply cleanly",
                             NULL,
                             &pg_plan_advice_feedback_warnings,
                             false,
                             PGC_USERSET,
                             0,
                             NULL,
                             NULL,
                             NULL);
 
    DefineCustomBoolVariable("pg_plan_advice.trace_mask",
                             "Emit debugging messages showing the computed strategy mask for each relation",
                             NULL,
                             &pg_plan_advice_trace_mask,
                             false,
                             PGC_USERSET,
                             0,
                             NULL,
                             NULL,
                             NULL);
 
    MarkGUCPrefixReserved("pg_plan_advice");
 
    /* Get an ID that we can use to cache data in an ExplainState. */
    es_extension_id = GetExplainExtensionId("pg_plan_advice");
 
    /* Register the new EXPLAIN options implemented by this module. */
    RegisterExtensionExplainOption("plan_advice",
                                   pg_plan_advice_explain_option_handler,
                                   GUCCheckBooleanExplainOption);
 
    /* Install hooks */
    pgpa_planner_install_hooks();
    prev_explain_per_plan = explain_per_plan_hook;
    explain_per_plan_hook = pg_plan_advice_explain_per_plan_hook;
}

References DefineCustomBoolVariable(), DefineCustomStringVariable(), es_extension_id, explain_per_plan_hook, fb(), GetExplainExtensionId(), GUCCheckBooleanExplainOption(), MarkGUCPrefixReserved(), pg_plan_advice_advice, pg_plan_advice_advice_check_hook(), pg_plan_advice_always_explain_supplied_advice, pg_plan_advice_always_store_advice_details, pg_plan_advice_explain_option_handler(), pg_plan_advice_explain_per_plan_hook(), pg_plan_advice_feedback_warnings, pg_plan_advice_trace_mask, PGC_USERSET, pgpa_planner_install_hooks(), prev_explain_per_plan, and RegisterExtensionExplainOption().

◆ find_defelem_by_defname()

static DefElem * find_defelem_by_defname	(	List *	deflist,
		char *	defname
	)

static

Definition at line 448 of file pg_plan_advice.c.

{
    foreach_node(DefElem, item, deflist)
    {
        if (strcmp(item->defname, defname) == 0)
            return item;
    }
 
    return NULL;
}

References fb(), and foreach_node.

Referenced by pg_plan_advice_explain_per_plan_hook().

◆ pg_plan_advice_add_advisor()

void pg_plan_advice_add_advisor ( pg_plan_advice_advisor_hook hook )

Definition at line 205 of file pg_plan_advice.c.

{
    MemoryContext oldcontext;
 
    oldcontext = MemoryContextSwitchTo(pg_plan_advice_get_mcxt());
    advisor_hook_list = lappend(advisor_hook_list, hook);
    MemoryContextSwitchTo(oldcontext);
}

References advisor_hook_list, lappend(), MemoryContextSwitchTo(), and pg_plan_advice_get_mcxt().

◆ pg_plan_advice_advice_check_hook()

static bool pg_plan_advice_advice_check_hook	(	char **	newval,
		void **	extra,
		GucSource	source
	)

static

Definition at line 413 of file pg_plan_advice.c.

{
    MemoryContext oldcontext;
    MemoryContext tmpcontext;
    char       *error;
 
    if (*newval == NULL)
        return true;
 
    tmpcontext = AllocSetContextCreate(CurrentMemoryContext,
                                       "pg_plan_advice.advice",
                                       ALLOCSET_DEFAULT_SIZES);
    oldcontext = MemoryContextSwitchTo(tmpcontext);
 
    /*
     * It would be nice to save the parse tree that we construct here for
     * eventual use when planning with this advice, but *extra can only point
     * to a single guc_malloc'd chunk, and our parse tree involves an
     * arbitrary number of memory allocations.
     */
    (void) pgpa_parse(*newval, &error);
 
    if (error != NULL)
        GUC_check_errdetail("Could not parse advice: %s", error);
 
    MemoryContextSwitchTo(oldcontext);
    MemoryContextDelete(tmpcontext);
 
    return (error == NULL);
}

References ALLOCSET_DEFAULT_SIZES, AllocSetContextCreate, CurrentMemoryContext, error(), fb(), GUC_check_errdetail, MemoryContextDelete(), MemoryContextSwitchTo(), newval, and pgpa_parse().

Referenced by _PG_init().

◆ pg_plan_advice_explain_feedback()

static void pg_plan_advice_explain_feedback	(	ExplainState *	es,
		List *	feedback
	)

static

Definition at line 322 of file pg_plan_advice.c.

{
    StringInfoData buf;
 
    initStringInfo(&buf);
    foreach_node(DefElem, item, feedback)
    {
        int         flags = defGetInt32(item);
 
        appendStringInfo(&buf, "%s /* ", item->defname);
        pgpa_trove_append_flags(&buf, flags);
        appendStringInfoString(&buf, " */\n");
    }
 
    pg_plan_advice_explain_text_multiline(es, "Supplied Plan Advice",
                                          buf.data);
}

References appendStringInfo(), appendStringInfoString(), buf, defGetInt32(), fb(), foreach_node, initStringInfo(), pg_plan_advice_explain_text_multiline(), and pgpa_trove_append_flags().

Referenced by pg_plan_advice_explain_per_plan_hook().

◆ pg_plan_advice_explain_option_handler()

static void pg_plan_advice_explain_option_handler	(	ExplainState *	es,
		DefElem *	opt,
		ParseState *	pstate
	)

static

Definition at line 257 of file pg_plan_advice.c.

{
    bool       *plan_advice;
 
    plan_advice = GetExplainExtensionState(es, es_extension_id);
 
    if (plan_advice == NULL)
    {
        plan_advice = palloc0_object(bool);
        SetExplainExtensionState(es, es_extension_id, plan_advice);
    }
 
    *plan_advice = defGetBoolean(opt);
}

References defGetBoolean(), es_extension_id, fb(), GetExplainExtensionState(), palloc0_object, and SetExplainExtensionState().

Referenced by _PG_init().

◆ pg_plan_advice_explain_per_plan_hook()

static void pg_plan_advice_explain_per_plan_hook	(	PlannedStmt *	plannedstmt,
		IntoClause *	into,
		ExplainState *	es,
		const char *	queryString,
		ParamListInfo	params,
		QueryEnvironment *	queryEnv
	)

static

Definition at line 344 of file pg_plan_advice.c.

{
    bool        should_explain;
    DefElem    *pgpa_item;
    List       *pgpa_list;
 
    if (prev_explain_per_plan)
        prev_explain_per_plan(plannedstmt, into, es, queryString, params,
                              queryEnv);
 
    /* Should an advice string be part of the EXPLAIN output? */
    should_explain = pg_plan_advice_should_explain(es);
 
    /* Find any data pgpa_planner_shutdown stashed in the PlannedStmt. */
    pgpa_item = find_defelem_by_defname(plannedstmt->extension_state,
                                        "pg_plan_advice");
    pgpa_list = pgpa_item == NULL ? NULL : (List *) pgpa_item->arg;
 
    /*
     * By default, if there is a record of attempting to apply advice during
     * query planning, we always output that information, but the user can set
     * pg_plan_advice.always_explain_supplied_advice = false to suppress that
     * behavior. If they do, we'll only display it when the PLAN_ADVICE option
     * was specified and not set to false.
     *
     * NB: If we're explaining a query planned beforehand -- i.e. a prepared
     * statement -- the application of query advice may not have been
     * recorded, and therefore this won't be able to show anything. Use
     * pg_plan_advice.always_store_advice_details = true to work around this.
     */
    if (pgpa_list != NULL && (pg_plan_advice_always_explain_supplied_advice ||
                              should_explain))
    {
        DefElem    *feedback;
 
        feedback = find_defelem_by_defname(pgpa_list, "feedback");
        if (feedback != NULL)
            pg_plan_advice_explain_feedback(es, (List *) feedback->arg);
    }
 
    /*
     * If the PLAN_ADVICE option was specified -- and not set to FALSE -- show
     * generated advice.
     */
    if (should_explain)
    {
        DefElem    *advice_string_item;
        char       *advice_string = NULL;
 
        advice_string_item =
            find_defelem_by_defname(pgpa_list, "advice_string");
        if (advice_string_item != NULL)
        {
            advice_string = strVal(advice_string_item->arg);
            pg_plan_advice_explain_text_multiline(es, "Generated Plan Advice",
                                                  advice_string);
        }
    }
}

References PlannedStmt::extension_state, fb(), find_defelem_by_defname(), pg_plan_advice_always_explain_supplied_advice, pg_plan_advice_explain_feedback(), pg_plan_advice_explain_text_multiline(), pg_plan_advice_should_explain(), prev_explain_per_plan, and strVal.

Referenced by _PG_init().

◆ pg_plan_advice_explain_text_multiline()

static void pg_plan_advice_explain_text_multiline	(	ExplainState *	es,
		char *	qlabel,
		char *	value
	)

static

Definition at line 278 of file pg_plan_advice.c.

{
    char       *s;
 
    /* For non-text formats, it's best not to add any special handling. */
    if (es->format != EXPLAIN_FORMAT_TEXT)
    {
        ExplainPropertyText(qlabel, value, es);
        return;
    }
 
    /* In text format, if there is no data, display nothing. */
    if (*value == '\0')
        return;
 
    /*
     * It looks nicest to indent each line of the advice separately, beginning
     * on the line below the label.
     */
    ExplainIndentText(es);
    appendStringInfo(es->str, "%s:\n", qlabel);
    es->indent++;
    while ((s = strchr(value, '\n')) != NULL)
    {
        ExplainIndentText(es);
        appendBinaryStringInfo(es->str, value, (s - value) + 1);
        value = s + 1;
    }
 
    /* Don't interpret a terminal newline as a request for an empty line. */
    if (*value != '\0')
    {
        ExplainIndentText(es);
        appendStringInfo(es->str, "%s\n", value);
    }
 
    es->indent--;
}

References appendBinaryStringInfo(), appendStringInfo(), EXPLAIN_FORMAT_TEXT, ExplainIndentText(), ExplainPropertyText(), fb(), ExplainState::format, ExplainState::indent, ExplainState::str, and value.

Referenced by pg_plan_advice_explain_feedback(), and pg_plan_advice_explain_per_plan_hook().

◆ pg_plan_advice_get_mcxt()

MemoryContext pg_plan_advice_get_mcxt ( void )

Definition at line 143 of file pg_plan_advice.c.

{
    if (pgpa_memory_context == NULL)
        pgpa_memory_context = AllocSetContextCreate(TopMemoryContext,
                                                    "pg_plan_advice",
                                                    ALLOCSET_DEFAULT_SIZES);
 
    return pgpa_memory_context;
}

References ALLOCSET_DEFAULT_SIZES, AllocSetContextCreate, fb(), pgpa_memory_context, and TopMemoryContext.

Referenced by pg_plan_advice_add_advisor(), and pg_plan_advice_remove_advisor().

◆ pg_plan_advice_get_supplied_query_advice()

char * pg_plan_advice_get_supplied_query_advice	(	PlannerGlobal *	glob,
		Query *	parse,
		const char *	query_string,
		int	cursorOptions,
		ExplainState *	es
	)

Definition at line 170 of file pg_plan_advice.c.

{
    ListCell   *lc;
 
    /*
     * If any advisors are loaded, consult them. The first one that produces a
     * non-NULL string wins.
     */
    foreach(lc, advisor_hook_list)
    {
        pg_plan_advice_advisor_hook hook = lfirst(lc);
        char       *advice_string;
 
        advice_string = (*hook) (glob, parse, query_string, cursorOptions, es);
        if (advice_string != NULL)
            return advice_string;
    }
 
    /* Otherwise, just use the value of the GUC. */
    return pg_plan_advice_advice;
}

References advisor_hook_list, fb(), lfirst, parse(), and pg_plan_advice_advice.

Referenced by pgpa_planner_setup().

◆ pg_plan_advice_remove_advisor()

void pg_plan_advice_remove_advisor ( pg_plan_advice_advisor_hook hook )

Definition at line 218 of file pg_plan_advice.c.

{
    MemoryContext oldcontext;
 
    oldcontext = MemoryContextSwitchTo(pg_plan_advice_get_mcxt());
    advisor_hook_list = list_delete_ptr(advisor_hook_list, hook);
    MemoryContextSwitchTo(oldcontext);
}

References advisor_hook_list, list_delete_ptr(), MemoryContextSwitchTo(), and pg_plan_advice_get_mcxt().

◆ pg_plan_advice_request_advice_generation()

void pg_plan_advice_request_advice_generation ( bool activate )

Definition at line 242 of file pg_plan_advice.c.

{
    if (activate)
        pgpa_planner_generate_advice++;
    else
    {
        Assert(pgpa_planner_generate_advice > 0);
        pgpa_planner_generate_advice--;
    }
}

References Assert, fb(), and pgpa_planner_generate_advice.

◆ pg_plan_advice_should_explain()

bool pg_plan_advice_should_explain ( ExplainState * es )

Definition at line 157 of file pg_plan_advice.c.

{
    bool       *plan_advice = NULL;
 
    if (es != NULL)
        plan_advice = GetExplainExtensionState(es, es_extension_id);
    return plan_advice != NULL && *plan_advice;
}

References es_extension_id, fb(), and GetExplainExtensionState().

Referenced by pg_plan_advice_explain_per_plan_hook(), and pgpa_planner_setup().

Variable Documentation

◆ advisor_hook_list

List* advisor_hook_list = NIL

static

Definition at line 46 of file pg_plan_advice.c.

Referenced by pg_plan_advice_add_advisor(), pg_plan_advice_get_supplied_query_advice(), and pg_plan_advice_remove_advisor().

◆ es_extension_id

int es_extension_id

static

Definition at line 44 of file pg_plan_advice.c.

Referenced by _PG_init(), pg_plan_advice_explain_option_handler(), and pg_plan_advice_should_explain().

◆ PG_MODULE_MAGIC

PG_MODULE_MAGIC

Definition at line 31 of file pg_plan_advice.c.

◆ pg_plan_advice_advice

char* pg_plan_advice_advice = NULL

Definition at line 34 of file pg_plan_advice.c.

Referenced by _PG_init(), and pg_plan_advice_get_supplied_query_advice().

◆ pg_plan_advice_always_explain_supplied_advice

bool pg_plan_advice_always_explain_supplied_advice = true

static

Definition at line 36 of file pg_plan_advice.c.

Referenced by _PG_init(), and pg_plan_advice_explain_per_plan_hook().

◆ pg_plan_advice_always_store_advice_details

bool pg_plan_advice_always_store_advice_details = false

Definition at line 35 of file pg_plan_advice.c.

Referenced by _PG_init(), and pgpa_planner_setup().

◆ pg_plan_advice_feedback_warnings

bool pg_plan_advice_feedback_warnings = false

Definition at line 37 of file pg_plan_advice.c.

Referenced by _PG_init(), pgpa_planner_setup(), and pgpa_planner_shutdown().

◆ pg_plan_advice_trace_mask

bool pg_plan_advice_trace_mask = false

Definition at line 38 of file pg_plan_advice.c.

Referenced by _PG_init(), pgpa_build_simple_rel(), pgpa_join_path_setup(), and pgpa_joinrel_setup().

◆ pgpa_memory_context

MemoryContext pgpa_memory_context = NULL

static

Definition at line 45 of file pg_plan_advice.c.

Referenced by pg_plan_advice_get_mcxt().

◆ prev_explain_per_plan

explain_per_plan_hook_type prev_explain_per_plan = NULL

static

Definition at line 41 of file pg_plan_advice.c.

Referenced by _PG_init(), and pg_plan_advice_explain_per_plan_hook().

Variables
	PG_MODULE_MAGIC

char *	pg_plan_advice_advice = NULL

bool	pg_plan_advice_always_store_advice_details = false

static bool	pg_plan_advice_always_explain_supplied_advice = true

bool	pg_plan_advice_feedback_warnings = false

bool	pg_plan_advice_trace_mask = false

static explain_per_plan_hook_type	prev_explain_per_plan = NULL

static int	es_extension_id

static MemoryContext	pgpa_memory_context = NULL

static List *	advisor_hook_list = NIL

Functions

Variables

Function Documentation

◆ _PG_init()

◆ find_defelem_by_defname()

◆ pg_plan_advice_add_advisor()

◆ pg_plan_advice_advice_check_hook()

◆ pg_plan_advice_explain_feedback()

◆ pg_plan_advice_explain_option_handler()

◆ pg_plan_advice_explain_per_plan_hook()

◆ pg_plan_advice_explain_text_multiline()

◆ pg_plan_advice_get_mcxt()

◆ pg_plan_advice_get_supplied_query_advice()

◆ pg_plan_advice_remove_advisor()

◆ pg_plan_advice_request_advice_generation()

◆ pg_plan_advice_should_explain()

Variable Documentation

◆ advisor_hook_list

◆ es_extension_id

◆ PG_MODULE_MAGIC

◆ pg_plan_advice_advice

◆ pg_plan_advice_always_explain_supplied_advice

◆ pg_plan_advice_always_store_advice_details

◆ pg_plan_advice_feedback_warnings

◆ pg_plan_advice_trace_mask

◆ pgpa_memory_context

◆ prev_explain_per_plan