explain_state.h File Reference

#include "nodes/parsenodes.h"
#include "nodes/plannodes.h"
#include "parser/parse_node.h"
#include "port/pg_bitutils.h"

Include dependency graph for explain_state.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	ExplainWorkersState
struct	ExplainState

Typedefs
typedef enum ExplainSerializeOption	ExplainSerializeOption
typedef enum ExplainFormat	ExplainFormat
typedef struct ExplainWorkersState	ExplainWorkersState
typedef struct ExplainState	ExplainState
typedef void(*	ExplainOptionHandler) (ExplainState *, DefElem *, ParseState *)
typedef bool(*	ExplainOptionGUCCheckHandler) (const char *option_name, const char *option_value, NodeTag option_type)
typedef void(*	explain_validate_options_hook_type) (ExplainState *es, List *options, ParseState *pstate)

Enumerations
enum	ExplainSerializeOption { EXPLAIN_SERIALIZE_NONE , EXPLAIN_SERIALIZE_TEXT , EXPLAIN_SERIALIZE_BINARY }
enum	ExplainFormat { EXPLAIN_FORMAT_TEXT , EXPLAIN_FORMAT_XML , EXPLAIN_FORMAT_JSON , EXPLAIN_FORMAT_YAML }

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
PGDLLIMPORT explain_validate_options_hook_type	explain_validate_options_hook

Typedef Documentation

explain_validate_options_hook_type

typedef void(* explain_validate_options_hook_type) (ExplainState *es, List *options, ParseState *pstate)

Definition at line 87 of file explain_state.h.

ExplainFormat

typedef enum ExplainFormat ExplainFormat

ExplainOptionGUCCheckHandler

typedef bool(* ExplainOptionGUCCheckHandler) (const char *option_name, const char *option_value, NodeTag option_type)

Definition at line 82 of file explain_state.h.

ExplainOptionHandler

typedef void(* ExplainOptionHandler) (ExplainState *, DefElem *, ParseState *)

Definition at line 81 of file explain_state.h.

ExplainSerializeOption

typedef enum ExplainSerializeOption ExplainSerializeOption

ExplainState

typedef struct ExplainState ExplainState

ExplainWorkersState

typedef struct ExplainWorkersState ExplainWorkersState

Enumeration Type Documentation

ExplainFormat

enum ExplainFormat

Enumerator
EXPLAIN_FORMAT_TEXT
EXPLAIN_FORMAT_XML
EXPLAIN_FORMAT_JSON
EXPLAIN_FORMAT_YAML

Definition at line 28 of file explain_state.h.

{
    EXPLAIN_FORMAT_TEXT,
    EXPLAIN_FORMAT_XML,
    EXPLAIN_FORMAT_JSON,
    EXPLAIN_FORMAT_YAML,
} ExplainFormat;

ExplainSerializeOption

enum ExplainSerializeOption

Enumerator
EXPLAIN_SERIALIZE_NONE
EXPLAIN_SERIALIZE_TEXT
EXPLAIN_SERIALIZE_BINARY

Definition at line 21 of file explain_state.h.

{
    EXPLAIN_SERIALIZE_NONE,
    EXPLAIN_SERIALIZE_TEXT,
    EXPLAIN_SERIALIZE_BINARY,
} ExplainSerializeOption;

Function Documentation

ApplyExtensionExplainOption()

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

extern

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 )

extern

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  )

extern

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  )

extern

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  )

extern

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  )

extern

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  )

extern

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  )

extern

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  )

extern

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

PGDLLIMPORT explain_validate_options_hook_type explain_validate_options_hook

extern

Definition at line 43 of file explain_state.c.

Referenced by ParseExplainOptionList().