explain_state.c

Go to the documentation of this file.

/*-------------------------------------------------------------------------
 *
 * explain_state.c
 *    Code for initializing and accessing ExplainState objects
 *
 * Portions Copyright (c) 1996-2026, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994-5, Regents of the University of California
 *
 * In-core options have hard-coded fields inside ExplainState; e.g. if
 * the user writes EXPLAIN (BUFFERS) then ExplainState's "buffers" member
 * will be set to true. Extensions can also register options using
 * RegisterExtensionExplainOption; so that e.g. EXPLAIN (BICYCLE 'red')
 * will invoke a designated handler that knows what the legal values are
 * for the BICYCLE option. However, it's not enough for an extension to be
 * able to parse new options: it also needs a place to store the results
 * of that parsing, and an ExplainState has no 'bicycle' field.
 *
 * To solve this problem, an ExplainState can contain an array of opaque
 * pointers, one per extension. An extension can use GetExplainExtensionId
 * to acquire an integer ID to acquire an offset into this array that is
 * reserved for its exclusive use, and then use GetExplainExtensionState
 * and SetExplainExtensionState to read and write its own private state
 * within an ExplainState.
 *
 * Note that there is no requirement that the name of the option match
 * the name of the extension; e.g. a pg_explain_conveyance extension could
 * implement options for BICYCLE, MONORAIL, etc.
 *
 * IDENTIFICATION
 *    src/backend/commands/explain_state.c
 *
 *-------------------------------------------------------------------------
 */
#include "postgres.h"
 
#include "commands/defrem.h"
#include "commands/explain.h"
#include "commands/explain_state.h"
#include "utils/builtins.h"
#include "utils/guc.h"
 
/* Hook to perform additional EXPLAIN options validation */
explain_validate_options_hook_type explain_validate_options_hook = NULL;
 
typedef struct
{
    const char *option_name;
    ExplainOptionHandler option_handler;
    ExplainOptionGUCCheckHandler guc_check_handler;
} ExplainExtensionOption;
 
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;
 
/*
 * Create a new ExplainState struct initialized with default options.
 */
ExplainState *
NewExplainState(void)
{
    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;
}
 
/*
 * Parse a list of EXPLAIN options and update an ExplainState accordingly.
 */
void
ParseExplainOptionList(ExplainState *es, List *options, ParseState *pstate)
{
    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);
}
 
/*
 * Map the name of an EXPLAIN extension to an integer ID.
 *
 * Within the lifetime of a particular backend, the same name will be mapped
 * to the same ID every time. IDs are not stable across backends. Use the ID
 * that you get from this function to call GetExplainExtensionState and
 * SetExplainExtensionState.
 *
 * extension_name is assumed to be a constant string or allocated in storage
 * that will never be freed.
 */
int
GetExplainExtensionId(const char *extension_name)
{
    /* 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++;
}
 
/*
 * Get extension-specific state from an ExplainState.
 *
 * See comments for SetExplainExtensionState, below.
 */
void *
GetExplainExtensionState(ExplainState *es, int extension_id)
{
    Assert(extension_id >= 0);
 
    if (extension_id >= es->extension_state_allocated)
        return NULL;
 
    return es->extension_state[extension_id];
}
 
/*
 * Store extension-specific state into an ExplainState.
 *
 * To use this function, first obtain an integer extension_id using
 * GetExplainExtensionId. Then use this function to store an opaque pointer
 * in the ExplainState. Later, you can retrieve the opaque pointer using
 * GetExplainExtensionState.
 */
void
SetExplainExtensionState(ExplainState *es, int extension_id, void *opaque)
{
    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;
}
 
/*
 * Register a new EXPLAIN option.
 *
 * option_name is assumed to be a constant string or allocated in storage
 * that will never be freed.
 *
 * When option_name is used as an EXPLAIN option, handler will be called and
 * should update the ExplainState passed to it. See comments at top of file
 * for a more detailed explanation.
 *
 * guc_check_handler is a function that can be safely called from a
 * GUC check hook to validate a proposed value for a custom EXPLAIN option.
 * Boolean-valued options can pass GUCCheckBooleanExplainOption. See the
 * comments for GUCCheckBooleanExplainOption for further information on
 * how a guc_check_handler should behave.
 */
void
RegisterExtensionExplainOption(const char *option_name,
                               ExplainOptionHandler handler,
                               ExplainOptionGUCCheckHandler guc_check_handler)
{
    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;
}
 
/*
 * Apply an EXPLAIN option registered by an extension.
 *
 * If no extension has registered the named option, returns false. Otherwise,
 * calls the appropriate handler function and then returns true.
 */
bool
ApplyExtensionExplainOption(ExplainState *es, DefElem *opt, ParseState *pstate)
{
    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;
}
 
/*
 * Determine whether an EXPLAIN extension option will be accepted without
 * error. Returns true if so, and false if not. See the comments for
 * GUCCheckBooleanExplainOption for more details.
 *
 * The caller need not know that the option_name is valid; this function
 * will indicate that the option is unrecognized if that is the case.
 */
bool
GUCCheckExplainExtensionOption(const char *option_name,
                               const char *option_value,
                               NodeTag option_type)
{
    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;
}
 
/*
 * guc_check_handler for Boolean-valued EXPLAIN extension options.
 *
 * After receiving a "true" value from this or any other GUC check handler
 * for an EXPLAIN extension option, the caller is entitled to assume that
 * a suitably constructed DefElem passed to the main option handler will
 * not cause an error. To construct this DefElem, the caller should set
 * the DefElem's defname to option_name. If option_values is NULL, arg
 * should be NULL. Otherwise, arg should be of the type given by
 * option_type, with option_value as the associated value. The only option
 * types that should be passed are T_String, T_Float, and T_Integer; in
 * the last case, the caller will need to perform a string-to-integer
 * conversion.
 *
 * A guc_check_handler should not throw an error, and should not allocate
 * memory.  If it returns false to indicate that the option_value is not
 * acceptable, it may use GUC_check_errmsg(), GUC_check_errdetail(), etc.
 * to clarify the nature of the problem.
 *
 * Since we're concerned with Boolean options here, the logic below must
 * exactly match the semantics of defGetBoolean.
 */
bool
GUCCheckBooleanExplainOption(const char *option_name,
                             const char *option_value,
                             NodeTag option_type)
{
    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;
}