/*-------------------------------------------------------------------------
 *
 * explain_state.h
 *	  prototypes for explain_state.c
 *
 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994-5, Regents of the University of California
 *
 * src/include/commands/explain_state.h
 *
 *-------------------------------------------------------------------------
 */
#ifndef EXPLAIN_STATE_H
#define EXPLAIN_STATE_H

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

typedef enum ExplainSerializeOption
{
	EXPLAIN_SERIALIZE_NONE,
	EXPLAIN_SERIALIZE_TEXT,
	EXPLAIN_SERIALIZE_BINARY,
} ExplainSerializeOption;

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

typedef struct ExplainWorkersState
{
	int			num_workers;	/* # of worker processes the plan used */
	bool	   *worker_inited;	/* per-worker state-initialized flags */
	StringInfoData *worker_str; /* per-worker transient output buffers */
	int		   *worker_state_save;	/* per-worker grouping state save areas */
	StringInfo	prev_str;		/* saved output buffer while redirecting */
} ExplainWorkersState;

typedef struct ExplainState
{
	StringInfo	str;			/* output buffer */
	/* options */
	bool		verbose;		/* be verbose */
	bool		analyze;		/* print actual times */
	bool		costs;			/* print estimated costs */
	bool		buffers;		/* print buffer usage */
	bool		wal;			/* print WAL usage */
	bool		timing;			/* print detailed node timing */
	bool		summary;		/* print total planning and execution timing */
	bool		memory;			/* print planner's memory usage information */
	bool		settings;		/* print modified settings */
	bool		generic;		/* generate a generic plan */
	ExplainSerializeOption serialize;	/* serialize the query's output? */
	ExplainFormat format;		/* output format */
	/* state for output formatting --- not reset for each new plan tree */
	int			indent;			/* current indentation level */
	List	   *grouping_stack; /* format-specific grouping state */
	/* state related to the current plan tree (filled by ExplainPrintPlan) */
	PlannedStmt *pstmt;			/* top of plan */
	List	   *rtable;			/* range table */
	List	   *rtable_names;	/* alias names for RTEs */
	List	   *deparse_cxt;	/* context list for deparsing expressions */
	Bitmapset  *printed_subplans;	/* ids of SubPlans we've printed */
	bool		hide_workers;	/* set if we find an invisible Gather */
	int			rtable_size;	/* length of rtable excluding the RTE_GROUP
								 * entry */
	/* state related to the current plan node */
	ExplainWorkersState *workers_state; /* needed if parallel plan */
	/* extensions */
	void	  **extension_state;
	int			extension_state_allocated;
} ExplainState;

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

/* Hook to perform additional EXPLAIN options validation */
typedef void (*explain_validate_options_hook_type) (struct ExplainState *es, List *options,
													ParseState *pstate);
extern PGDLLIMPORT explain_validate_options_hook_type explain_validate_options_hook;

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

extern int	GetExplainExtensionId(const char *extension_name);
extern void *GetExplainExtensionState(ExplainState *es, int extension_id);
extern void SetExplainExtensionState(ExplainState *es, int extension_id,
									 void *opaque);

extern void RegisterExtensionExplainOption(const char *option_name,
										   ExplainOptionHandler handler);
extern bool ApplyExtensionExplainOption(ExplainState *es, DefElem *opt,
										ParseState *pstate);

#endif							/* EXPLAIN_STATE_H */