explain_state.c File Reference

#include "postgres.h"
#include "commands/defrem.h"
#include "commands/explain.h"
#include "commands/explain_state.h"
#include "utils/builtins.h"
#include "utils/guc.h"

Include dependency graph for explain_state.c:

Go to the source code of this file.

Data Structures
struct	ExplainExtensionOption

Functions
ExplainState *	NewExplainState (void)
void	ParseExplainOptionList (ExplainState *es, List *options, ParseState *pstate)
int	GetExplainExtensionId (const char *extension_name)
void *	GetExplainExtensionState (ExplainState *es, int extension_id)
void	SetExplainExtensionState (ExplainState *es, int extension_id, void *opaque)
void	RegisterExtensionExplainOption (const char *option_name, ExplainOptionHandler handler, ExplainOptionGUCCheckHandler guc_check_handler)
bool	ApplyExtensionExplainOption (ExplainState *es, DefElem *opt, ParseState *pstate)
bool	GUCCheckExplainExtensionOption (const char *option_name, const char *option_value, NodeTag option_type)
bool	GUCCheckBooleanExplainOption (const char *option_name, const char *option_value, NodeTag option_type)

Variables
explain_validate_options_hook_type	explain_validate_options_hook = NULL
static const char **	ExplainExtensionNameArray = NULL
static int	ExplainExtensionNamesAssigned = 0
static int	ExplainExtensionNamesAllocated = 0
static ExplainExtensionOption *	ExplainExtensionOptionArray = NULL
static int	ExplainExtensionOptionsAssigned = 0
static int	ExplainExtensionOptionsAllocated = 0

Function Documentation

ApplyExtensionExplainOption()

bool ApplyExtensionExplainOption	(	ExplainState *	es,
		DefElem *	opt,
		ParseState *	pstate
	)

Definition at line 389 of file explain_state.c.

{
    for (int i = 0; i < ExplainExtensionOptionsAssigned; ++i)
    {
        if (strcmp(ExplainExtensionOptionArray[i].option_name,
                   opt->defname) == 0)
        {
            ExplainExtensionOptionArray[i].option_handler(es, opt, pstate);
            return true;
        }
    }
 
    return false;
}

References DefElem::defname, ExplainExtensionOptionArray, ExplainExtensionOptionsAssigned, fb(), i, and ExplainExtensionOption::option_handler.

Referenced by apply_extension_options(), and ParseExplainOptionList().

GetExplainExtensionId()

int GetExplainExtensionId

(

const char *

extension_name

)

Definition at line 232 of file explain_state.c.

{
    /* Search for an existing extension by this name; if found, return ID. */
    for (int i = 0; i < ExplainExtensionNamesAssigned; ++i)
        if (strcmp(ExplainExtensionNameArray[i], extension_name) == 0)
            return i;
 
    /* If there is no array yet, create one. */
    if (ExplainExtensionNameArray == NULL)
    {
        ExplainExtensionNamesAllocated = 16;
        ExplainExtensionNameArray = (const char **)
            MemoryContextAlloc(TopMemoryContext,
                               ExplainExtensionNamesAllocated
                               * sizeof(char *));
    }
 
    /* If there's an array but it's currently full, expand it. */
    if (ExplainExtensionNamesAssigned >= ExplainExtensionNamesAllocated)
    {
        int         i = pg_nextpower2_32(ExplainExtensionNamesAssigned + 1);
 
        ExplainExtensionNameArray = (const char **)
            repalloc(ExplainExtensionNameArray, i * sizeof(char *));
        ExplainExtensionNamesAllocated = i;
    }
 
    /* Assign and return new ID. */
    ExplainExtensionNameArray[ExplainExtensionNamesAssigned] = extension_name;
    return ExplainExtensionNamesAssigned++;
}

References ExplainExtensionNameArray, ExplainExtensionNamesAllocated, ExplainExtensionNamesAssigned, fb(), i, MemoryContextAlloc(), pg_nextpower2_32(), repalloc(), and TopMemoryContext.

Referenced by _PG_init().

GetExplainExtensionState()

void * GetExplainExtensionState	(	ExplainState *	es,
		int	extension_id
	)

Definition at line 270 of file explain_state.c.

{
    Assert(extension_id >= 0);
 
    if (extension_id >= es->extension_state_allocated)
        return NULL;
 
    return es->extension_state[extension_id];
}

References Assert, ExplainState::extension_state, ExplainState::extension_state_allocated, and fb().

Referenced by overexplain_ensure_options(), overexplain_per_node_hook(), overexplain_per_plan_hook(), pg_plan_advice_explain_option_handler(), and pg_plan_advice_should_explain().

GUCCheckBooleanExplainOption()

bool GUCCheckBooleanExplainOption	(	const char *	option_name,
		const char *	option_value,
		NodeTag	option_type
	)

Definition at line 454 of file explain_state.c.

{
    bool        valid = false;
 
    if (option_value == NULL)
    {
        /* defGetBoolean treats no argument as valid */
        valid = true;
    }
    else if (option_type == T_String)
    {
        /* defGetBoolean accepts exactly these string values */
        if (pg_strcasecmp(option_value, "true") == 0 ||
            pg_strcasecmp(option_value, "false") == 0 ||
            pg_strcasecmp(option_value, "on") == 0 ||
            pg_strcasecmp(option_value, "off") == 0)
            valid = true;
    }
    else if (option_type == T_Integer)
    {
        long        value;
        char       *end;
 
        /*
         * defGetBoolean accepts only 0 and 1, but those can be spelled in
         * various ways (e.g. 01, 0x01).
         */
        errno = 0;
        value = strtol(option_value, &end, 0);
        if (errno == 0 && *end == '\0' && end != option_value &&
            value == (int) value && (value == 0 || value == 1))
            valid = true;
    }
 
    if (!valid)
    {
        GUC_check_errmsg("EXPLAIN option \"%s\" requires a Boolean value",
                         option_name);
        return false;
    }
 
    return true;
}

References fb(), GUC_check_errmsg, option_type, pg_strcasecmp(), and value.

Referenced by _PG_init().

GUCCheckExplainExtensionOption()

bool GUCCheckExplainExtensionOption	(	const char *	option_name,
		const char *	option_value,
		NodeTag	option_type
	)

Definition at line 413 of file explain_state.c.

{
    for (int i = 0; i < ExplainExtensionOptionsAssigned; i++)
    {
        ExplainExtensionOption *exopt = &ExplainExtensionOptionArray[i];
 
        if (strcmp(exopt->option_name, option_name) == 0)
            return exopt->guc_check_handler(option_name, option_value,
                                            option_type);
    }
 
    /* Unrecognized option name. */
    GUC_check_errmsg("unrecognized EXPLAIN option \"%s\"", option_name);
    return false;
}

References ExplainExtensionOptionArray, ExplainExtensionOptionsAssigned, fb(), GUC_check_errmsg, ExplainExtensionOption::guc_check_handler, i, and option_type.

Referenced by check_log_extension_options().

NewExplainState()

ExplainState * NewExplainState

(

void

)

Definition at line 64 of file explain_state.c.

{
    ExplainState *es = palloc0_object(ExplainState);
 
    /* Set default options (most fields can be left as zeroes). */
    es->costs = true;
    /* Prepare output buffer. */
    es->str = makeStringInfo();
 
    return es;
}

References ExplainState::costs, makeStringInfo(), palloc0_object, and ExplainState::str.

Referenced by explain_ExecutorEnd(), and ExplainQuery().

ParseExplainOptionList()

void ParseExplainOptionList	(	ExplainState *	es,
		List *	options,
		ParseState *	pstate
	)

Definition at line 80 of file explain_state.c.

{
    ListCell   *lc;
    bool        timing_set = false;
    bool        buffers_set = false;
    bool        summary_set = false;
 
    /* Parse options list. */
    foreach(lc, options)
    {
        DefElem    *opt = (DefElem *) lfirst(lc);
 
        if (strcmp(opt->defname, "analyze") == 0)
            es->analyze = defGetBoolean(opt);
        else if (strcmp(opt->defname, "verbose") == 0)
            es->verbose = defGetBoolean(opt);
        else if (strcmp(opt->defname, "costs") == 0)
            es->costs = defGetBoolean(opt);
        else if (strcmp(opt->defname, "buffers") == 0)
        {
            buffers_set = true;
            es->buffers = defGetBoolean(opt);
        }
        else if (strcmp(opt->defname, "wal") == 0)
            es->wal = defGetBoolean(opt);
        else if (strcmp(opt->defname, "settings") == 0)
            es->settings = defGetBoolean(opt);
        else if (strcmp(opt->defname, "generic_plan") == 0)
            es->generic = defGetBoolean(opt);
        else if (strcmp(opt->defname, "timing") == 0)
        {
            timing_set = true;
            es->timing = defGetBoolean(opt);
        }
        else if (strcmp(opt->defname, "summary") == 0)
        {
            summary_set = true;
            es->summary = defGetBoolean(opt);
        }
        else if (strcmp(opt->defname, "memory") == 0)
            es->memory = defGetBoolean(opt);
        else if (strcmp(opt->defname, "serialize") == 0)
        {
            if (opt->arg)
            {
                char       *p = defGetString(opt);
 
                if (strcmp(p, "off") == 0 || strcmp(p, "none") == 0)
                    es->serialize = EXPLAIN_SERIALIZE_NONE;
                else if (strcmp(p, "text") == 0)
                    es->serialize = EXPLAIN_SERIALIZE_TEXT;
                else if (strcmp(p, "binary") == 0)
                    es->serialize = EXPLAIN_SERIALIZE_BINARY;
                else
                    ereport(ERROR,
                            (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
                             errmsg("unrecognized value for %s option \"%s\": \"%s\"",
                                    "EXPLAIN", opt->defname, p),
                             parser_errposition(pstate, opt->location)));
            }
            else
            {
                /* SERIALIZE without an argument is taken as 'text' */
                es->serialize = EXPLAIN_SERIALIZE_TEXT;
            }
        }
        else if (strcmp(opt->defname, "format") == 0)
        {
            char       *p = defGetString(opt);
 
            if (strcmp(p, "text") == 0)
                es->format = EXPLAIN_FORMAT_TEXT;
            else if (strcmp(p, "xml") == 0)
                es->format = EXPLAIN_FORMAT_XML;
            else if (strcmp(p, "json") == 0)
                es->format = EXPLAIN_FORMAT_JSON;
            else if (strcmp(p, "yaml") == 0)
                es->format = EXPLAIN_FORMAT_YAML;
            else
                ereport(ERROR,
                        (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
                         errmsg("unrecognized value for %s option \"%s\": \"%s\"",
                                "EXPLAIN", opt->defname, p),
                         parser_errposition(pstate, opt->location)));
        }
        else if (strcmp(opt->defname, "io") == 0)
            es->io = defGetBoolean(opt);
        else if (!ApplyExtensionExplainOption(es, opt, pstate))
            ereport(ERROR,
                    (errcode(ERRCODE_SYNTAX_ERROR),
                     errmsg("unrecognized %s option \"%s\"",
                            "EXPLAIN", opt->defname),
                     parser_errposition(pstate, opt->location)));
    }
 
    /* check that WAL is used with EXPLAIN ANALYZE */
    if (es->wal && !es->analyze)
        ereport(ERROR,
                (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
                 errmsg("EXPLAIN option %s requires ANALYZE", "WAL")));
 
    /* if the timing was not set explicitly, set default value */
    es->timing = (timing_set) ? es->timing : es->analyze;
 
    /* if the buffers was not set explicitly, set default value */
    es->buffers = (buffers_set) ? es->buffers : es->analyze;
 
    /* check that timing is used with EXPLAIN ANALYZE */
    if (es->timing && !es->analyze)
        ereport(ERROR,
                (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
                 errmsg("EXPLAIN option %s requires ANALYZE", "TIMING")));
 
    /* check that IO is used with EXPLAIN ANALYZE */
    if (es->io && !es->analyze)
        ereport(ERROR,
                (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
                 errmsg("EXPLAIN option %s requires ANALYZE", "IO")));
 
    /* check that serialize is used with EXPLAIN ANALYZE */
    if (es->serialize != EXPLAIN_SERIALIZE_NONE && !es->analyze)
        ereport(ERROR,
                (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
                 errmsg("EXPLAIN option %s requires ANALYZE", "SERIALIZE")));
 
    /* check that GENERIC_PLAN is not used with EXPLAIN ANALYZE */
    if (es->generic && es->analyze)
        ereport(ERROR,
                (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
                 errmsg("%s options %s and %s cannot be used together",
                        "EXPLAIN", "ANALYZE", "GENERIC_PLAN")));
 
    /* if the summary was not set explicitly, set default value */
    es->summary = (summary_set) ? es->summary : es->analyze;
 
    /* plugin specific option validation */
    if (explain_validate_options_hook)
        (*explain_validate_options_hook) (es, options, pstate);
}

References ExplainState::analyze, ApplyExtensionExplainOption(), DefElem::arg, ExplainState::buffers, ExplainState::costs, defGetBoolean(), defGetString(), DefElem::defname, ereport, errcode(), errmsg, ERROR, EXPLAIN_FORMAT_JSON, EXPLAIN_FORMAT_TEXT, EXPLAIN_FORMAT_XML, EXPLAIN_FORMAT_YAML, EXPLAIN_SERIALIZE_BINARY, EXPLAIN_SERIALIZE_NONE, EXPLAIN_SERIALIZE_TEXT, explain_validate_options_hook, fb(), ExplainState::format, ExplainState::generic, ExplainState::io, lfirst, DefElem::location, ExplainState::memory, parser_errposition(), ExplainState::serialize, ExplainState::settings, ExplainState::summary, ExplainState::timing, ExplainState::verbose, and ExplainState::wal.

Referenced by ExplainQuery().

RegisterExtensionExplainOption()

void RegisterExtensionExplainOption	(	const char *	option_name,
		ExplainOptionHandler	handler,
		ExplainOptionGUCCheckHandler	guc_check_handler
	)

Definition at line 332 of file explain_state.c.

{
    ExplainExtensionOption *exopt;
 
    Assert(handler != NULL);
    Assert(guc_check_handler != NULL);
 
    /* Search for an existing option by this name; if found, update handler. */
    for (int i = 0; i < ExplainExtensionOptionsAssigned; ++i)
    {
        if (strcmp(ExplainExtensionOptionArray[i].option_name,
                   option_name) == 0)
        {
            exopt = &ExplainExtensionOptionArray[i];
 
            exopt->option_handler = handler;
            exopt->guc_check_handler = guc_check_handler;
            return;
        }
    }
 
    /* If there is no array yet, create one. */
    if (ExplainExtensionOptionArray == NULL)
    {
        ExplainExtensionOptionsAllocated = 16;
        ExplainExtensionOptionArray = (ExplainExtensionOption *)
            MemoryContextAlloc(TopMemoryContext,
                               ExplainExtensionOptionsAllocated
                               * sizeof(ExplainExtensionOption));
    }
 
    /* If there's an array but it's currently full, expand it. */
    if (ExplainExtensionOptionsAssigned >= ExplainExtensionOptionsAllocated)
    {
        int         i = pg_nextpower2_32(ExplainExtensionOptionsAssigned + 1);
 
        ExplainExtensionOptionArray = (ExplainExtensionOption *)
            repalloc(ExplainExtensionOptionArray, i * sizeof(ExplainExtensionOption));
        ExplainExtensionOptionsAllocated = i;
    }
 
    /* Assign and return new ID. */
    exopt = &ExplainExtensionOptionArray[ExplainExtensionOptionsAssigned++];
    exopt->option_name = option_name;
    exopt->option_handler = handler;
    exopt->guc_check_handler = guc_check_handler;
}

References Assert, ExplainExtensionOptionArray, ExplainExtensionOptionsAllocated, ExplainExtensionOptionsAssigned, fb(), i, MemoryContextAlloc(), ExplainExtensionOption::option_handler, ExplainExtensionOption::option_name, pg_nextpower2_32(), repalloc(), and TopMemoryContext.

Referenced by _PG_init().

SetExplainExtensionState()

void SetExplainExtensionState	(	ExplainState *	es,
		int	extension_id,
		void *	opaque
	)

Definition at line 289 of file explain_state.c.

{
    Assert(extension_id >= 0);
 
    /* If there is no array yet, create one. */
    if (es->extension_state == NULL)
    {
        es->extension_state_allocated =
            Max(16, pg_nextpower2_32(extension_id + 1));
        es->extension_state =
            palloc0(es->extension_state_allocated * sizeof(void *));
    }
 
    /* If there's an array but it's currently full, expand it. */
    if (extension_id >= es->extension_state_allocated)
    {
        int         i;
 
        i = pg_nextpower2_32(extension_id + 1);
        es->extension_state = repalloc0_array(es->extension_state, void *, es->extension_state_allocated, i);
        es->extension_state_allocated = i;
    }
 
    es->extension_state[extension_id] = opaque;
}

References Assert, ExplainState::extension_state, ExplainState::extension_state_allocated, fb(), i, Max, palloc0(), pg_nextpower2_32(), and repalloc0_array.

Referenced by overexplain_ensure_options(), and pg_plan_advice_explain_option_handler().

Variable Documentation

explain_validate_options_hook

explain_validate_options_hook_type explain_validate_options_hook = NULL

Definition at line 43 of file explain_state.c.

Referenced by ParseExplainOptionList().

ExplainExtensionNameArray

const char** ExplainExtensionNameArray = NULL

static

Definition at line 52 of file explain_state.c.

Referenced by GetExplainExtensionId().

ExplainExtensionNamesAllocated

int ExplainExtensionNamesAllocated = 0

static

Definition at line 54 of file explain_state.c.

Referenced by GetExplainExtensionId().

ExplainExtensionNamesAssigned

int ExplainExtensionNamesAssigned = 0

static

Definition at line 53 of file explain_state.c.

Referenced by GetExplainExtensionId().

ExplainExtensionOptionArray

ExplainExtensionOption* ExplainExtensionOptionArray = NULL

static

Definition at line 56 of file explain_state.c.

Referenced by ApplyExtensionExplainOption(), GUCCheckExplainExtensionOption(), and RegisterExtensionExplainOption().

ExplainExtensionOptionsAllocated

int ExplainExtensionOptionsAllocated = 0

static

Definition at line 58 of file explain_state.c.

Referenced by RegisterExtensionExplainOption().

ExplainExtensionOptionsAssigned

int ExplainExtensionOptionsAssigned = 0

static

Definition at line 57 of file explain_state.c.

Referenced by ApplyExtensionExplainOption(), GUCCheckExplainExtensionOption(), and RegisterExtensionExplainOption().