explain_state.h File Reference

#include "nodes/parsenodes.h"
#include "nodes/plannodes.h"
#include "parser/parse_node.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 void(*	explain_validate_options_hook_type) (struct 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)
bool	ApplyExtensionExplainOption (ExplainState *es, DefElem *opt, ParseState *pstate)

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) (struct ExplainState *es, List *options, ParseState *pstate)

Definition at line 82 of file explain_state.h.

ExplainFormat

typedef enum ExplainFormat ExplainFormat

ExplainOptionHandler

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

Definition at line 79 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 27 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 20 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
	)

Definition at line 365 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, i, and ExplainExtensionOption::option_handler.

Referenced by ParseExplainOptionList().

GetExplainExtensionId()

int GetExplainExtensionId

(

const char *

extension_name

)

Definition at line 220 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, i, MemoryContextAlloc(), pg_nextpower2_32(), repalloc(), and TopMemoryContext.

Referenced by _PG_init().

GetExplainExtensionState()

void * GetExplainExtensionState	(	ExplainState *	es,
		int	extension_id
	)

Definition at line 258 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, and ExplainState::extension_state_allocated.

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

NewExplainState()

ExplainState * NewExplainState

(

void

)

Definition at line 61 of file explain_state.c.

{
    ExplainState *es = (ExplainState *) palloc0(sizeof(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(), and ExplainState::str.

Referenced by explain_ExecutorEnd(), and ExplainQuery().

ParseExplainOptionList()

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

Definition at line 77 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 EXPLAIN option \"%s\": \"%s\"",
                                    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 EXPLAIN option \"%s\": \"%s\"",
                                opt->defname, p),
                         parser_errposition(pstate, opt->location)));
        }
        else if (!ApplyExtensionExplainOption(es, opt, pstate))
            ereport(ERROR,
                    (errcode(ERRCODE_SYNTAX_ERROR),
                     errmsg("unrecognized EXPLAIN option \"%s\"",
                            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 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("EXPLAIN options ANALYZE and GENERIC_PLAN cannot be used together")));
 
    /* 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, ExplainState::format, ExplainState::generic, if(), lfirst, DefElem::location, ExplainState::memory, options, 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
	)

Definition at line 316 of file explain_state.c.

{
    ExplainExtensionOption *exopt;
 
    /* 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)
        {
            ExplainExtensionOptionArray[i].option_handler = handler;
            return;
        }
    }
 
    /* If there is no array yet, create one. */
    if (ExplainExtensionOptionArray == NULL)
    {
        ExplainExtensionOptionsAllocated = 16;
        ExplainExtensionOptionArray = (ExplainExtensionOption *)
            MemoryContextAlloc(TopMemoryContext,
                               ExplainExtensionOptionsAllocated
                               * sizeof(char *));
    }
 
    /* 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(char *));
        ExplainExtensionOptionsAllocated = i;
    }
 
    /* Assign and return new ID. */
    exopt = &ExplainExtensionOptionArray[ExplainExtensionOptionsAssigned++];
    exopt->option_name = option_name;
    exopt->option_handler = handler;
}

References ExplainExtensionOptionArray, ExplainExtensionOptionsAllocated, ExplainExtensionOptionsAssigned, 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 277 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 = 16;
        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(es->extension_state_allocated + 1);
        es->extension_state = (void **)
            repalloc0(es->extension_state,
                      es->extension_state_allocated * sizeof(void *),
                      i * sizeof(void *));
        es->extension_state_allocated = i;
    }
 
    es->extension_state[extension_id] = opaque;
}

References Assert(), ExplainState::extension_state, ExplainState::extension_state_allocated, i, palloc0(), pg_nextpower2_32(), and repalloc0().

Referenced by overexplain_ensure_options().

Variable Documentation

explain_validate_options_hook

PGDLLIMPORT explain_validate_options_hook_type explain_validate_options_hook

extern

Definition at line 41 of file explain_state.c.

Referenced by ParseExplainOptionList().