PostgreSQL 源码解读（83）- 查询语句#68（PortalStart函数）
本节介绍了PortalStart函数，该函数在create_simple_query中被调用，用于执行前初始化portal结构体中的相关信息。
一、数据结构
Portal
包括场景PortalStrategy枚举定义/PortalStatus状态定义/PortalData结构体.Portal是PortalData结构体指针,详见代码注释.
/*
* We have several execution strategies for Portals, depending on what
* query or queries are to be executed. (Note: in all cases, a Portal
* executes just a single source-SQL query, and thus produces just a
* single result from the user's viewpoint. However, the rule rewriter
* may expand the single source query to zero or many actual queries.)
* 对于Portals(客户端请求)，有几种执行策略，具体取决于要执行什么查询。
* (注意:无论什么情况下，一个Portal只执行一个source-SQL查询，因此从用户的角度来看只产生一个结果。
* 但是，规则重写器可以将单个源查询扩展为零或多个实际查询。
*
* PORTAL_ONE_SELECT: the portal contains one single SELECT query. We run
* the Executor incrementally as results are demanded. This strategy also
* supports holdable cursors (the Executor results can be dumped into a
* tuplestore for access after transaction completion).
* PORTAL_ONE_SELECT: 包含一个SELECT查询。
* 按需要的结果重复(递增)地运行执行器。
* 该策略还支持可持有游标(执行器结果可以在事务完成后转储到tuplestore中进行访问)。
*
* PORTAL_ONE_RETURNING: the portal contains a single INSERT/UPDATE/DELETE
* query with a RETURNING clause (plus possibly auxiliary queries added by
* rule rewriting). On first execution, we run the portal to completion
* and dump the primary query's results into the portal tuplestore; the
* results are then returned to the client as demanded. (We can't support
* suspension of the query partway through, because the AFTER TRIGGER code
* can't cope, and also because we don't want to risk failing to execute
* all the auxiliary queries.)
* PORTAL_ONE_RETURNING: 包含一个带有RETURNING子句的INSERT/UPDATE/DELETE查询
(可能还包括由规则重写添加的辅助查询)。
* 在第一次执行时，运行Portal来完成并将主查询的结果转储到Portal的tuplestore中;
* 然后根据需要将结果返回给客户端。
* (我们不能支持半途中断的查询，因为AFTER触发器代码无法处理，
* 也因为不想冒执行所有辅助查询失败的风险)。
*
* PORTAL_ONE_MOD_WITH: the portal contains one single SELECT query, but
* it has data-modifying CTEs. This is currently treated the same as the
* PORTAL_ONE_RETURNING case because of the possibility of needing to fire
* triggers. It may act more like PORTAL_ONE_SELECT in future.
* PORTAL_ONE_MOD_WITH: 只包含一个SELECT查询，但它具有数据修改的CTEs。
* 这与PORTAL_ONE_RETURNING的情况相同，因为可能需要触发触发器。将来它的行为可能更像PORTAL_ONE_SELECT。
*
* PORTAL_UTIL_SELECT: the portal contains a utility statement that returns
* a SELECT-like result (for example, EXPLAIN or SHOW). On first execution,
* we run the statement and dump its results into the portal tuplestore;
* the results are then returned to the client as demanded.
* PORTAL_UTIL_SELECT: 包含一个实用程序语句，该语句返回一个类似SELECT的结果(例如，EXPLAIN或SHOW)。
* 在第一次执行时，运行语句并将其结果转储到portal tuplestore;然后根据需要将结果返回给客户端。
*
* PORTAL_MULTI_QUERY: all other cases. Here, we do not support partial
* execution: the portal's queries will be run to completion on first call.
* PORTAL_MULTI_QUERY: 除上述情况外的其他情况。
* 在这里，不支持部分执行:Portal的查询语句将在第一次调用时运行到完成。
*/
typedef enum PortalStrategy
{
PORTAL_ONE_SELECT,
PORTAL_ONE_RETURNING,
PORTAL_ONE_MOD_WITH,
PORTAL_UTIL_SELECT,
PORTAL_MULTI_QUERY
} PortalStrategy;
/*
* A portal is always in one of these states. It is possible to transit
* from ACTIVE back to READY if the query is not run to completion;
* otherwise we never back up in status.
* Portal总是处于这些状态中的之一。
* 如果查询没有运行到完成，则可以从活动状态转回准备状态;否则永远不会后退。
*/
typedef enum PortalStatus
{
PORTAL_NEW, /* 刚创建;freshly created */
PORTAL_DEFINED, /* PortalDefineQuery完成;PortalDefineQuery done */
PORTAL_READY, /* PortalStart完成;PortalStart complete, can run it */
PORTAL_ACTIVE, /* Portal正在运行;portal is running (can't delete it) */
PORTAL_DONE, /* Portal已经完成;portal is finished (don't re-run it) */
PORTAL_FAILED /* Portal出现错误;portal got error (can't re-run it) */
} PortalStatus;
typedef struct PortalData *Portal;//结构体指针
typedef struct PortalData
{
/* Bookkeeping data */
const char *name; /* portal的名称;portal's name */
const char *prepStmtName; /* 已完成准备的源语句;source prepared statement (NULL if none) */
MemoryContext portalContext; /* 内存上下文;subsidiary memory for portal */
ResourceOwner resowner; /* 资源的owner;resources owned by portal */
void (*cleanup) (Portal portal); /* cleanup钩子函数;cleanup hook */
/*
* State data for remembering which subtransaction(s) the portal was
* created or used in. If the portal is held over from a previous
* transaction, both subxids are InvalidSubTransactionId. Otherwise,
* createSubid is the creating subxact and activeSubid is the last subxact
* in which we ran the portal.
* 状态数据，用于记住在哪个子事务中创建或使用Portal。
* 如果Portal是从以前的事务中持有的，那么两个subxids都应该是InvalidSubTransactionId。
* 否则，createSubid是正在创建的subxact，而activeSubid是运行Portal的最后一个subxact。
*/
SubTransactionId createSubid; /* 正在创建的subxact;the creating subxact */
SubTransactionId activeSubid; /* 活动的最后一个subxact;the last subxact with activity */
/* The query or queries the portal will execute */
//portal将会执行的查询
const char *sourceText; /* 查询的源文本;text of query (as of 8.4, never NULL) */
const char *commandTag; /* 源查询的命令tag;command tag for original query */
List *stmts; /* PlannedStmt链表;list of PlannedStmts */
CachedPlan *cplan; /* 缓存的PlannedStmts;CachedPlan, if stmts are from one */
ParamListInfo portalParams; /* 传递给查询的参数;params to pass to query */
QueryEnvironment *queryEnv; /* 查询的执行环境;environment for query */
/* Features/options */
PortalStrategy strategy; /* 场景;see above */
int cursorOptions; /* DECLARE CURSOR选项位;DECLARE CURSOR option bits */
bool run_once; /* 是否只执行一次;portal will only be run once */
/* Status data */
PortalStatus status; /* Portal的状态;see above */
bool portalPinned; /* 是否不能被清除;a pinned portal can't be dropped */
bool autoHeld; /* 是否自动从pinned到held;was automatically converted from pinned to
* held (see HoldPinnedPortals()) */
/* If not NULL, Executor is active; call ExecutorEnd eventually: */
//如不为NULL,执行器处于活动状态
QueryDesc *queryDesc; /* 执行器需要使用的信息;info needed for executor invocation */
/* If portal returns tuples, this is their tupdesc: */
//如Portal需要返回元组,这是元组的描述
TupleDesc tupDesc; /* 结果元组的描述;descriptor for result tuples */
/* and these are the format codes to use for the columns: */
//列信息的格式码
int16 *formats; /* 每一列的格式码;a format code for each column */
/*
* Where we store tuples for a held cursor or a PORTAL_ONE_RETURNING or
* PORTAL_UTIL_SELECT query. (A cursor held past the end of its
* transaction no longer has any active executor state.)
* 在这里，为持有的游标或PORTAL_ONE_RETURNING或PORTAL_UTIL_SELECT存储元组。
* (在事务结束后持有的游标不再具有任何活动执行器状态。)
*/
Tuplestorestate *holdStore; /* 存储持有的游标信息;store for holdable cursors */
MemoryContext holdContext; /* 持有holdStore的内存上下文;memory containing holdStore */
/*
* Snapshot under which tuples in the holdStore were read. We must keep a
* reference to this snapshot if there is any possibility that the tuples
* contain TOAST references, because releasing the snapshot could allow
* recently-dead rows to be vacuumed away, along with any toast data
* belonging to them. In the case of a held cursor, we avoid needing to
* keep such a snapshot by forcibly detoasting the data.
* 读取holdStore中元组的Snapshot。
* 如果元组包含TOAST引用的可能性存在，那么必须保持对该快照的引用，
* 因为释放快照可能会使最近废弃的行与属于它们的TOAST数据一起被清除。
* 对于持有的游标，通过强制解压数据来避免需要保留这样的快照。
*/
Snapshot holdSnapshot; /* 已注册的快照信息,如无则为NULL;registered snapshot, or NULL if none */
/*
* atStart, atEnd and portalPos indicate the current cursor position.
* portalPos is zero before the first row, N after fetching N'th row of
* query. After we run off the end, portalPos = # of rows in query, and
* atEnd is true. Note that atStart implies portalPos == 0, but not the
* reverse: we might have backed up only as far as the first row, not to
* the start. Also note that various code inspects atStart and atEnd, but
* only the portal movement routines should touch portalPos.
* atStart、atEnd和portalPos表示当前光标的位置。
* portalPos在第一行之前为0，在获取第N行查询后为N。
* 在运行结束后，portalPos = #查询中的行号，atEnd为T。
* 注意，atStart表示portalPos == 0，但不是相反:我们可能只回到到第一行，而不是开始。
* 还要注意，各种代码在开始和结束时都要检查，但是只有Portal移动例程应该访问portalPos。
*/
bool atStart;//处于开始位置?
bool atEnd;//处于结束位置?
uint64 portalPos;//实际行号
/* Presentation data, primarily used by the pg_cursors system view */
//用于表示的数据，主要由pg_cursors系统视图使用
TimestampTz creation_time; /* portal定义的时间;time at which this portal was defined */
bool visible; /* 是否在pg_cursors中可见? include this portal in pg_cursors? */
} PortalData;
/*
* PortalIsValid
* True iff portal is valid.
* 判断Portal是否有效
*/
#define PortalIsValid(p) PointerIsValid(p)
QueryDesc
QueryDesc封装了执行器执行查询所需的所有内容。
/* ----------------
* query descriptor:
*
* a QueryDesc encapsulates everything that the executor
* needs to execute the query.
* QueryDesc封装了执行器执行查询所需的所有内容。
*
* For the convenience of SQL-language functions, we also support QueryDescs
* containing utility statements; these must not be passed to the executor
* however.
* 为了使用SQL函数，还需要支持包含实用语句的QueryDescs;
* 但是，这些内容不能传递给执行程序。
* ---------------------
*/
typedef struct QueryDesc
{
/* These fields are provided by CreateQueryDesc */
//以下变量由CreateQueryDesc函数设置
CmdType operation; /* 操作类型,如CMD_SELECT等;CMD_SELECT, CMD_UPDATE, etc. */
PlannedStmt *plannedstmt; /* 已规划的语句,规划器的输出;planner's output (could be utility, too) */
const char *sourceText; /* 源SQL文本;source text of the query */
Snapshot snapshot; /* 查询使用的快照;snapshot to use for query */
Snapshot crosscheck_snapshot; /* RI 更新/删除交叉检查快照;crosscheck for RI update/delete */
DestReceiver *dest; /* 元组输出的接收器;the destination for tuple output */
ParamListInfo params; /* 需传入的参数值;param values being passed in */
QueryEnvironment *queryEnv; /* 查询环境变量;query environment passed in */
int instrument_options; /* InstrumentOption选项;OR of InstrumentOption flags */
/* These fields are set by ExecutorStart */
//以下变量由ExecutorStart函数设置
TupleDesc tupDesc; /* 结果元组tuples描述;descriptor for result tuples */
EState *estate; /* 执行器状态;executor's query-wide state */
PlanState *planstate; /* per-plan-node状态树;tree of per-plan-node state */
/* This field is set by ExecutorRun */
//以下变量由ExecutorRun设置
bool already_executed; /* 先前已执行,则为T;true if previously executed */
/* This is always set NULL by the core system, but plugins can change it */
//内核设置为NULL,可由插件修改
struct Instrumentation *totaltime; /* ExecutorRun函数所花费的时间;total time spent in ExecutorRun */
} QueryDesc;
二、源码解读
PortalStart
PortalStart函数的作用是在执行SQL语句前初始化portal结构体中的相关信息，其中有2个重要数据结构的初始化:
1.调用CreateQueryDesc函数结构体QueryDesc
2.调用ExecutorStart函数初始化结构体EState,ExecutorStart函数调用InitPlan(下一节介绍)初始化计划状态树.
/*
* PortalStart
* Prepare a portal for execution.
* 执行前初始化portal结构体中的相关信息
*
* Caller must already have created the portal, done PortalDefineQuery(),
* and adjusted portal options if needed.
* 调用者必须已经创建了portal,完成PortalDefineQuery()函数的调用,并且已经调整了portal中的相关选项
*
* If parameters are needed by the query, they must be passed in "params"
* (caller is responsible for giving them appropriate lifetime).
* 如果查询需要提供参数,通过"params"参数传入
* (调用者负责参数的生命周期管理)
*
* The caller can also provide an initial set of "eflags" to be passed to
* ExecutorStart (but note these can be modified internally, and they are
* currently only honored for PORTAL_ONE_SELECT portals). Most callers
* should simply pass zero.
* 调用者需要提供"eflags"变量的初始化集合,该参数用于传递给函数ExecutorStart
* (要注意eflags可以在内部修改,它们目前只在PORTAL_ONE_SELECT中才会被使用)
* 大多数的调用者只应该传递参数0
*
* The caller can optionally pass a snapshot to be used; pass InvalidSnapshot
* for the normal behavior of setting a new snapshot. This parameter is
* presently ignored for non-PORTAL_ONE_SELECT portals (it's only intended
* to be used for cursors).
* 调用者可以选择传递要使用的快照;为设置新快照的正常行为传递InvalidSnapshot。
* 这个参数目前仅用于PORTAL_ONE_SELECT使用(用于游标)。
*
* On return, portal is ready to accept PortalRun() calls, and the result
* tupdesc (if any) is known.
* 该函数返回时,portal已做好接收PortalRun()调用返回的准备,结果tupdesc是已知的.
*/
void
PortalStart(Portal portal, ParamListInfo params,
int eflags, Snapshot snapshot)
{
Portal saveActivePortal;
ResourceOwner saveResourceOwner;
MemoryContext savePortalContext;
MemoryContext oldContext;
QueryDesc *queryDesc;
int myeflags;
AssertArg(PortalIsValid(portal));
AssertState(portal->status == PORTAL_DEFINED);
/*
* Set up global portal context pointers.
* 设置全局portal上下文指针
*/
//保护"现场"
saveActivePortal = ActivePortal;
saveResourceOwner = CurrentResourceOwner;
savePortalContext = PortalContext;
PG_TRY();
{
ActivePortal = portal;
if (portal->resowner)
CurrentResourceOwner = portal->resowner;
PortalContext = portal->portalContext;
oldContext = MemoryContextSwitchTo(PortalContext);
/* Must remember portal param list, if any */
//记录传递的参数信息
portal->portalParams = params;
/*
* Determine the portal execution strategy
* 确定portal执行场景
*/
portal->strategy = ChoosePortalStrategy(portal->stmts);
/*
* Fire her up according to the strategy
* 根据场景触发相应的处理
*/
switch (portal->strategy)
{
case PORTAL_ONE_SELECT://PORTAL_ONE_SELECT
/* Must set snapshot before starting executor. */
//在开始执行前必须设置快照snapshot
if (snapshot)
PushActiveSnapshot(snapshot);
else
PushActiveSnapshot(GetTransactionSnapshot());
/*
* Create QueryDesc in portal's context; for the moment, set
* the destination to DestNone.
* 在portal上下文中创建QueryDesc,同时设置接收的目标为DestNone
*/
queryDesc = CreateQueryDesc(linitial_node(PlannedStmt, portal->stmts),
portal->sourceText,
GetActiveSnapshot(),
InvalidSnapshot,
None_Receiver,
params,
portal->queryEnv,
0);
/*
* If it's a scrollable cursor, executor needs to support
* REWIND and backwards scan, as well as whatever the caller
* might've asked for.
* 游标可滚动,执行器需要支持REWIND和向后的扫描
*/
if (portal->cursorOptions & CURSOR_OPT_SCROLL)
myeflags = eflags | EXEC_FLAG_REWIND | EXEC_FLAG_BACKWARD;
else
myeflags = eflags;
/*
* Call ExecutorStart to prepare the plan for execution
* 调用ExecutorStart,为执行做准备
*/
ExecutorStart(queryDesc, myeflags);
/*
* This tells PortalCleanup to shut down the executor
* 告知PortalCleanup关闭执行器
*/
portal->queryDesc = queryDesc;
/*
* Remember tuple descriptor (computed by ExecutorStart)
* 记录tuple描述符(queryDesc->tupDesc)
*/
portal->tupDesc = queryDesc->tupDesc;
/*
* Reset cursor position data to "start of query"
* 重置游标位置数据为"开始查询"
*/
portal->atStart = true;//开始的位置
portal->atEnd = false; /* 允许可获取数据;allow fetches */
portal->portalPos = 0;//游标位置
PopActiveSnapshot();
break;
case PORTAL_ONE_RETURNING:
case PORTAL_ONE_MOD_WITH:
/*
* We don't start the executor until we are told to run the
* portal. We do need to set up the result tupdesc.
* 执行器在调用的时候才会启动,需要配置结果tupdesc.
*
*/
{
PlannedStmt *pstmt;
pstmt = PortalGetPrimaryStmt(portal);//获取主stmt
portal->tupDesc =
ExecCleanTypeFromTL(pstmt->planTree->targetlist,
false);//设置元组描述符
}
/*
* Reset cursor position data to "start of query"
* 重置游标位置
*/
portal->atStart = true;
portal->atEnd = false; /* allow fetches */
portal->portalPos = 0;
break;
case PORTAL_UTIL_SELECT://PORTAL_UTIL_SELECT
/*
* We don't set snapshot here, because PortalRunUtility will
* take care of it if needed.
*/
{
PlannedStmt *pstmt = PortalGetPrimaryStmt(portal);
Assert(pstmt->commandType == CMD_UTILITY);
portal->tupDesc = UtilityTupleDescriptor(pstmt->utilityStmt);
}
/*
* Reset cursor position data to "start of query"
*/
portal->atStart = true;
portal->atEnd = false; /* allow fetches */
portal->portalPos = 0;
break;
case PORTAL_MULTI_QUERY://PORTAL_MULTI_QUERY
/* Need do nothing now */
portal->tupDesc = NULL;
break;
}
}
PG_CATCH();
{
/* Uncaught error while executing portal: mark it dead */
MarkPortalFailed(portal);
/* Restore global vars and propagate error */
ActivePortal = saveActivePortal;
CurrentResourceOwner = saveResourceOwner;
PortalContext = savePortalContext;
PG_RE_THROW();
}
PG_END_TRY();
MemoryContextSwitchTo(oldContext);
ActivePortal = saveActivePortal;
CurrentResourceOwner = saveResourceOwner;
PortalContext = savePortalContext;
portal->status = PORTAL_READY;
}
/*
* ChoosePortalStrategy
* Select portal execution strategy given the intended statement list.
* 根据预期的语句链表选择portal执行策略。
*
* The list elements can be Querys or PlannedStmts.
* That's more general than portals need, but plancache.c uses this too.
* 链表中的元素可以是Query或者是PlannedStmt.
* 这比portal需要的更普遍，plancache.c也用这个。
*
*
* See the comments in portal.h.
* 参见portal.h中的注释.
*/
PortalStrategy
ChoosePortalStrategy(List *stmts)
{
int nSetTag;
ListCell *lc;
/*
* PORTAL_ONE_SELECT and PORTAL_UTIL_SELECT need only consider the
* single-statement case, since there are no rewrite rules that can add
* auxiliary queries to a SELECT or a utility command. PORTAL_ONE_MOD_WITH
* likewise allows only one top-level statement.
* PORTAL_ONE_SELECT和PORTAL_UTIL_SELECT只需要考虑单语句的情况，
* 因为没有可以向SELECT或实用程序命令添加辅助查询的重写规则。
* PORTAL_ONE_MOD_WITH同样只允许一个最上层语句。
*/
if (list_length(stmts) == 1)//只有1条语句
{
Node *stmt = (Node *) linitial(stmts);//获取stmt
if (IsA(stmt, Query))//Query
{
Query *query = (Query *) stmt;
if (query->canSetTag)
{
if (query->commandType == CMD_SELECT)//查询命令
{
if (query->hasModifyingCTE)
return PORTAL_ONE_MOD_WITH;//存在可更新的CTE-->PORTAL_ONE_MOD_WITH
else
return PORTAL_ONE_SELECT;//单个查询语句
}
if (query->commandType == CMD_UTILITY)//工具语句
{
if (UtilityReturnsTuples(query->utilityStmt))//返回元组
return PORTAL_UTIL_SELECT;//PORTAL_UTIL_SELECT
/* it can't be ONE_RETURNING, so give up */
return PORTAL_MULTI_QUERY;//返回PORTAL_MULTI_QUERY
}
}
}
else if (IsA(stmt, PlannedStmt))//PlannedStmt,参见Query处理逻辑
{
PlannedStmt *pstmt = (PlannedStmt *) stmt;
if (pstmt->canSetTag)
{
if (pstmt->commandType == CMD_SELECT)
{
if (pstmt->hasModifyingCTE)
return PORTAL_ONE_MOD_WITH;
else
return PORTAL_ONE_SELECT;
}
if (pstmt->commandType == CMD_UTILITY)
{
if (UtilityReturnsTuples(pstmt->utilityStmt))
return PORTAL_UTIL_SELECT;
/* it can't be ONE_RETURNING, so give up */
return PORTAL_MULTI_QUERY;
}
}
}
else
elog(ERROR, "unrecognized node type: %d", (int) nodeTag(stmt));
}
//存在多条语句
/*
* PORTAL_ONE_RETURNING has to allow auxiliary queries added by rewrite.
* Choose PORTAL_ONE_RETURNING if there is exactly one canSetTag query and
* it has a RETURNING list.
* PORTAL_ONE_RETURNING必须允许通过重写添加辅助查询。
* 如果只有一个canSetTag查询，并且它有一个RETURNING链表，那么选择PORTAL_ONE_RETURNING。
*/
nSetTag = 0;
foreach(lc, stmts)//遍历
{
Node *stmt = (Node *) lfirst(lc);
if (IsA(stmt, Query))
{
Query *query = (Query *) stmt;
if (query->canSetTag)
{
if (++nSetTag > 1)
return PORTAL_MULTI_QUERY; /* no need to look further */
if (query->commandType == CMD_UTILITY ||
query->returningList == NIL)
return PORTAL_MULTI_QUERY; /* no need to look further */
}
}
else if (IsA(stmt, PlannedStmt))
{
PlannedStmt *pstmt = (PlannedStmt *) stmt;
if (pstmt->canSetTag)
{
if (++nSetTag > 1)
return PORTAL_MULTI_QUERY; /* no need to look further */
if (pstmt->commandType == CMD_UTILITY ||
!pstmt->hasReturning)
return PORTAL_MULTI_QUERY; /* no need to look further */
}
}
else
elog(ERROR, "unrecognized node type: %d", (int) nodeTag(stmt));
}
if (nSetTag == 1)
return PORTAL_ONE_RETURNING;
/* Else, it's the general case... */
//通常的情况
return PORTAL_MULTI_QUERY;
}
/*
* CreateQueryDesc
* 构造QueryDesc结构体
*/
QueryDesc *
CreateQueryDesc(PlannedStmt *plannedstmt,
const char *sourceText,
Snapshot snapshot,
Snapshot crosscheck_snapshot,
DestReceiver *dest,
ParamListInfo params,
QueryEnvironment *queryEnv,
int instrument_options)
{
QueryDesc *qd = (QueryDesc *) palloc(sizeof(QueryDesc));
qd->operation = plannedstmt->commandType; /* 操作类型;operation */
qd->plannedstmt = plannedstmt; /* 已规划的SQL语句;plan */
qd->sourceText = sourceText; /* 源SQL文本;query text */
qd->snapshot = RegisterSnapshot(snapshot); /* 快照;snapshot */
/* RI check snapshot */
qd->crosscheck_snapshot = RegisterSnapshot(crosscheck_snapshot);
qd->dest = dest; /* 输出的目标端;output dest */
qd->params = params; /* 传入到查询语句中的参数值;parameter values passed into query */
qd->queryEnv = queryEnv; //查询环境变量
qd->instrument_options = instrument_options; /* 是否需要instrumentation;instrumentation wanted? */
/* null these fields until set by ExecutorStart */
qd->tupDesc = NULL;//初始化为NULL
qd->estate = NULL;
qd->planstate = NULL;
qd->totaltime = NULL;
/* not yet executed */
qd->already_executed = false;//未执行
return qd;
}
/* ----------------------------------------------------------------
* ExecutorStart
*
* This routine must be called at the beginning of any execution of any
* query plan
* ExecutorStart必须在执行开始前调用.
*
* Takes a QueryDesc previously created by CreateQueryDesc (which is separate
* only because some places use QueryDescs for utility commands). The tupDesc
* field of the QueryDesc is filled in to describe the tuples that will be
* returned, and the internal fields (estate and planstate) are set up.
* 获取先前由CreateQueryDesc创建的QueryDesc(该数据结构是独立的，只是因为有些地方使用QueryDesc来执行实用命令)。
* 填充QueryDesc的tupDesc字段，以描述将要返回的元组，并设置内部字段(estate和planstate)。
*
* eflags contains flag bits as described in executor.h.
* eflags存储标志位(在executor.h中有说明)
*
* NB: the CurrentMemoryContext when this is called will become the parent
* of the per-query context used for this Executor invocation.
* 注意:CurrentMemoryContext会成为每个执行查询的上下文的parent
*
* We provide a function hook variable that lets loadable plugins
* get control when ExecutorStart is called. Such a plugin would
* normally call standard_ExecutorStart().
* 我们提供了一个函数钩子变量，可以让可加载插件在调用ExecutorStart时获得控制权。
* 这样的插件通常会调用standard_ExecutorStart()函数。
*
* ----------------------------------------------------------------
*/
void
ExecutorStart(QueryDesc *queryDesc, int eflags)
{
if (ExecutorStart_hook)//存在钩子函数
(*ExecutorStart_hook) (queryDesc, eflags);
else
standard_ExecutorStart(queryDesc, eflags);
}
void
standard_ExecutorStart(QueryDesc *queryDesc, int eflags)
{
EState *estate;
MemoryContext oldcontext;
/* sanity checks: queryDesc must not be started already */
Assert(queryDesc != NULL);
Assert(queryDesc->estate == NULL);
/*
* If the transaction is read-only, we need to check if any writes are
* planned to non-temporary tables. EXPLAIN is considered read-only.
* 如果事务是只读的，需要检查是否计划对非临时表进行写操作。
* EXPLAIN命令被认为是只读的。
*
* Don't allow writes in parallel mode. Supporting UPDATE and DELETE
* would require (a) storing the combocid hash in shared memory, rather
* than synchronizing it just once at the start of parallelism, and (b) an
* alternative to heap_update()'s reliance on xmax for mutual exclusion.
* INSERT may have no such troubles, but we forbid it to simplify the
* checks.
* 不要在并行模式下写。
* 支持更新和删除需要:
* (a)在共享内存中存储combocid散列，而不是在并行性开始时只同步一次;
* (b) heap_update()依赖xmax实现互斥的替代方法。
* INSERT可能没有这样的麻烦，但我们禁止它简化检查。
*
* We have lower-level defenses in CommandCounterIncrement and elsewhere
* against performing unsafe operations in parallel mode, but this gives a
* more user-friendly error message.
* 在CommandCounterIncrement和其他地方，对于在并行模式下执行不安全的操作，
* PG有较低级别的防御，这里提供了更用户友好的错误消息。
*/
if ((XactReadOnly || IsInParallelMode()) &&
!(eflags & EXEC_FLAG_EXPLAIN_ONLY))
ExecCheckXactReadOnly(queryDesc->plannedstmt);
/*
* Build EState, switch into per-query memory context for startup.
* 构建EState,切换至每个查询的上下文中,准备开启执行
*/
estate = CreateExecutorState();
queryDesc->estate = estate;
oldcontext = MemoryContextSwitchTo(estate->es_query_cxt);
/*
* Fill in external parameters, if any, from queryDesc; and allocate
* workspace for internal parameters
* 填充queryDesc的外部参数(如有);并为内部参数分配工作区
*/
estate->es_param_list_info = queryDesc->params;
if (queryDesc->plannedstmt->paramExecTypes != NIL)
{
int nParamExec;
nParamExec = list_length(queryDesc->plannedstmt->paramExecTypes);
estate->es_param_exec_vals = (ParamExecData *)
palloc0(nParamExec * sizeof(ParamExecData));
}
estate->es_sourceText = queryDesc->sourceText;
/*
* Fill in the query environment, if any, from queryDesc.
* 填充查询执行环境,从queryDesc中获得
*/
estate->es_queryEnv = queryDesc->queryEnv;
/*
* If non-read-only query, set the command ID to mark output tuples with
* 非只读查询,设置命令ID
*/
switch (queryDesc->operation)
{
case CMD_SELECT:
/*
* SELECT FOR [KEY] UPDATE/SHARE and modifying CTEs need to mark
* tuples
* SELECT FOR [KEY] UPDATE/SHARE和正在更新的CTEs需要标记元组
*/
if (queryDesc->plannedstmt->rowMarks != NIL ||
queryDesc->plannedstmt->hasModifyingCTE)
estate->es_output_cid = GetCurrentCommandId(true);
/*
* A SELECT without modifying CTEs can't possibly queue triggers,
* so force skip-triggers mode. This is just a marginal efficiency
* hack, since AfterTriggerBeginQuery/AfterTriggerEndQuery aren't
* all that expensive, but we might as well do it.
* 不带更新CTEs的SELECT不可能执行触发器,因此强制为EXEC_FLAG_SKIP_TRIGGERS标记.
* 这只是一个边际效益问题，因为AfterTriggerBeginQuery/AfterTriggerEndQuery成本并不高，但不妨这样做。
*/
if (!queryDesc->plannedstmt->hasModifyingCTE)
eflags |= EXEC_FLAG_SKIP_TRIGGERS;
break;
case CMD_INSERT:
case CMD_DELETE:
case CMD_UPDATE:
estate->es_output_cid = GetCurrentCommandId(true);
break;
default:
elog(ERROR, "unrecognized operation code: %d",
(int) queryDesc->operation);
break;
}
/*
* Copy other important information into the EState
* 拷贝其他重要的信息到EState数据结构中
*/
estate->es_snapshot = RegisterSnapshot(queryDesc->snapshot);
estate->es_crosscheck_snapshot = RegisterSnapshot(queryDesc->crosscheck_snapshot);
estate->es_top_eflags = eflags;
estate->es_instrument = queryDesc->instrument_options;
estate->es_jit_flags = queryDesc->plannedstmt->jitFlags;
/*
* Set up an AFTER-trigger statement context, unless told not to, or
* unless it's EXPLAIN-only mode (when ExecutorFinish won't be called).
* 设置AFTER-trigger语句上下文,除非明确不需要执行此操作或者是EXPLAIN-only模式
*/
if (!(eflags & (EXEC_FLAG_SKIP_TRIGGERS | EXEC_FLAG_EXPLAIN_ONLY)))
AfterTriggerBeginQuery();
/*
* Initialize the plan state tree
* 初始化计划状态树
*/
InitPlan(queryDesc, eflags);
MemoryContextSwitchTo(oldcontext);
}
三、跟踪分析
测试脚本如下
testdb=# explain select dw.*,grjf.grbh,grjf.xm,grjf.ny,grjf.je
testdb-# from t_dwxx dw,lateral (select gr.grbh,gr.xm,jf.ny,jf.je
testdb(# from t_grxx gr inner join t_jfxx jf
testdb(# on gr.dwbh = dw.dwbh
testdb(# and gr.grbh = jf.grbh) grjf
testdb-# order by dw.dwbh;
QUERY PLAN
------------------------------------------------------------------------------------------
Sort (cost=20070.93..20320.93 rows=100000 width=47)
Sort Key: dw.dwbh
-> Hash Join (cost=3754.00..8689.61 rows=100000 width=47)
Hash Cond: ((gr.dwbh)::text = (dw.dwbh)::text)
-> Hash Join (cost=3465.00..8138.00 rows=100000 width=31)
Hash Cond: ((jf.grbh)::text = (gr.grbh)::text)
-> Seq Scan on t_jfxx jf (cost=0.00..1637.00 rows=100000 width=20)
-> Hash (cost=1726.00..1726.00 rows=100000 width=16)
-> Seq Scan on t_grxx gr (cost=0.00..1726.00 rows=100000 width=16)
-> Hash (cost=164.00..164.00 rows=10000 width=20)
-> Seq Scan on t_dwxx dw (cost=0.00..164.00 rows=10000 width=20)
(11 rows)
启动gdb,设置断点,进入PortalStart函数
(gdb) b PortalStart
Breakpoint 1 at 0x8cb67b: file pquery.c, line 455.
(gdb) c
Continuing.
Breakpoint 1, PortalStart (portal=0x25cd468, params=0x0, eflags=0, snapshot=0x0) at pquery.c:455
455 AssertArg(PortalIsValid(portal));
校验并保护现场
455 AssertArg(PortalIsValid(portal));
(gdb) n
456 AssertState(portal->status == PORTAL_DEFINED);
(gdb)
461 saveActivePortal = ActivePortal;
(gdb)
462 saveResourceOwner = CurrentResourceOwner;
(gdb)
463 savePortalContext = PortalContext;
设置内存上下文,资源owner等信息
466 ActivePortal = portal;
(gdb)
467 if (portal->resowner)
(gdb)
468 CurrentResourceOwner = portal->resowner;
(gdb)
469 PortalContext = portal->portalContext;
(gdb)
471 oldContext = MemoryContextSwitchTo(PortalContext);
(gdb)
474 portal->portalParams = params;
场景为PORTAL_ONE_SELECT
(gdb) p portal->strategy
$1 = PORTAL_ONE_SELECT
根据strategy,进入相应的处理分支(PORTAL_ONE_SELECT)
设置快照
489 if (snapshot)
(gdb)
492 PushActiveSnapshot(GetTransactionSnapshot());
创建QueryDesc结构体
(gdb)
498 queryDesc = CreateQueryDesc(linitial_node(PlannedStmt, portal->stmts),
查看queryDesc结构体信息
(gdb) n
512 if (portal->cursorOptions & CURSOR_OPT_SCROLL)
(gdb) p *queryDesc
$2 = {operation = CMD_SELECT, plannedstmt = 0x2650df0,
sourceText = 0x2567eb8 "select dw.*,grjf.grbh,grjf.xm,grjf.ny,grjf.je \nfrom t_dwxx dw,lateral (select gr.grbh,gr.xm,jf.ny,jf.je \n", ' ' , "from t_grxx gr inner join t_jfxx jf \n", ' ' ...,
snapshot = 0x260ce10, crosscheck_snapshot = 0x0, dest = 0xf8f280 , params = 0x0, queryEnv = 0x0,
instrument_options = 0, tupDesc = 0x0, estate = 0x0, planstate = 0x0, already_executed = false, totaltime = 0x0}
设置标记位
(gdb) n
515 myeflags = eflags;
(gdb) p eflags
$3 = 0
进入ExecutorStart函数
(gdb) n
147 standard_ExecutorStart(queryDesc, eflags);
(gdb) step
standard_ExecutorStart (queryDesc=0x2657f68, eflags=0) at execMain.c:157
157 Assert(queryDesc != NULL);
ExecutorStart-->执行相关校验和判断
157 Assert(queryDesc != NULL);
(gdb) n
158 Assert(queryDesc->estate == NULL);
(gdb)
175 if ((XactReadOnly || IsInParallelMode()) &&
ExecutorStart-->创建EState,初始化EState结构体
(gdb)
182 estate = CreateExecutorState();
(gdb)
183 queryDesc->estate = estate;
(gdb) p *estate
$4 = {type = T_EState, es_direction = ForwardScanDirection, es_snapshot = 0x0, es_crosscheck_snapshot = 0x0,
es_range_table = 0x0, es_plannedstmt = 0x0, es_sourceText = 0x0, es_junkFilter = 0x0, es_output_cid = 0,
es_result_relations = 0x0, es_num_result_relations = 0, es_result_relation_info = 0x0, es_root_result_relations = 0x0,
es_num_root_result_relations = 0, es_tuple_routing_result_relations = 0x0, es_trig_target_relations = 0x0,
es_trig_tuple_slot = 0x0, es_trig_oldtup_slot = 0x0, es_trig_newtup_slot = 0x0, es_param_list_info = 0x0,
es_param_exec_vals = 0x0, es_queryEnv = 0x0, es_query_cxt = 0x2653e30, es_tupleTable = 0x0, es_rowMarks = 0x0,
es_processed = 0, es_lastoid = 0, es_top_eflags = 0, es_instrument = 0, es_finished = false, es_exprcontexts = 0x0,
es_subplanstates = 0x0, es_auxmodifytables = 0x0, es_per_tuple_exprcontext = 0x0, es_epqTuple = 0x0,
es_epqTupleSet = 0x0, es_epqScanDone = 0x0, es_use_parallel_mode = false, es_query_dsa = 0x0, es_jit_flags = 0,
es_jit = 0x0, es_jit_worker_instr = 0x0}
ExecutorStart-->EState结构体中的变量赋值
(gdb) n
185 oldcontext = MemoryContextSwitchTo(estate->es_query_cxt);
(gdb)
191 estate->es_param_list_info = queryDesc->params;
(gdb)
193 if (queryDesc->plannedstmt->paramExecTypes != NIL)
(gdb)
202 estate->es_sourceText = queryDesc->sourceText;
(gdb)
207 estate->es_queryEnv = queryDesc->queryEnv;
ExecutorStart-->根据queryDesc->operation的不同执行的处理
(gdb)
212 switch (queryDesc->operation)
(gdb)
220 if (queryDesc->plannedstmt->rowMarks != NIL ||
(gdb) p queryDesc->operation
$5 = CMD_SELECT
(gdb) n
221 queryDesc->plannedstmt->hasModifyingCTE)
(gdb)
220 if (queryDesc->plannedstmt->rowMarks != NIL ||
(gdb)
230 if (!queryDesc->plannedstmt->hasModifyingCTE)
(gdb)
231 eflags |= EXEC_FLAG_SKIP_TRIGGERS;
(gdb)
232 break;
ExecutorStart-->设置快照
(gdb) n
249 estate->es_snapshot = RegisterSnapshot(queryDesc->snapshot);
(gdb) p *queryDesc->snapshot
$6 = {satisfies = 0xa923ca , xmin = 1689, xmax = 1689, xip = 0x0, xcnt = 0, subxip = 0x0,
subxcnt = 0, suboverflowed = false, takenDuringRecovery = false, copied = true, curcid = 0, speculativeToken = 0,
active_count = 1, regd_count = 1, ph_node = {first_child = 0x0, next_sibling = 0x0, prev_or_parent = 0x0}, whenTaken = 0,
lsn = 0}
ExecutorStart-->设置其他EState中的变量
(gdb) n
250 estate->es_crosscheck_snapshot = RegisterSnapshot(queryDesc->crosscheck_snapshot);
(gdb) p *queryDesc->crosscheck_snapshot
Cannot access memory at address 0x0
(gdb) n
251 estate->es_top_eflags = eflags;
(gdb)
252 estate->es_instrument = queryDesc->instrument_options;
(gdb)
253 estate->es_jit_flags = queryDesc->plannedstmt->jitFlags;
(gdb)
259 if (!(eflags & (EXEC_FLAG_SKIP_TRIGGERS | EXEC_FLAG_EXPLAIN_ONLY)))
ExecutorStart-->执行InitPlan
(gdb)
265 InitPlan(queryDesc, eflags);
(gdb)
267 MemoryContextSwitchTo(oldcontext);
(gdb)
268 }
ExecutorStart-->查看QueryDesc和EState
(gdb) p *queryDesc
$7 = {operation = CMD_SELECT, plannedstmt = 0x2650df0,
sourceText = 0x2567eb8 "select dw.*,grjf.grbh,grjf.xm,grjf.ny,grjf.je \nfrom t_dwxx dw,lateral (select gr.grbh,gr.xm,jf.ny,jf.je \n", ' ' , "from t_grxx gr inner join t_jfxx jf \n", ' ' ...,
snapshot = 0x25e46c0, crosscheck_snapshot = 0x0, dest = 0xf8f280 , params = 0x0, queryEnv = 0x0,
instrument_options = 0, tupDesc = 0x2665058, estate = 0x2653f48, planstate = 0x2654160, already_executed = false,
totaltime = 0x0}
(gdb) p *estate
$8 = {type = T_EState, es_direction = ForwardScanDirection, es_snapshot = 0x25e46c0, es_crosscheck_snapshot = 0x0,
es_range_table = 0x264ec98, es_plannedstmt = 0x2650df0,
es_sourceText = 0x2567eb8 "select dw.*,grjf.grbh,grjf.xm,grjf.ny,grjf.je \nfrom t_dwxx dw,lateral (select gr.grbh,gr.xm,jf.ny,jf.je \n", ' ' , "from t_grxx gr inner join t_jfxx jf \n", ' ' ...,
es_junkFilter = 0x0, es_output_cid = 0, es_result_relations = 0x0, es_num_result_relations = 0,
es_result_relation_info = 0x0, es_root_result_relations = 0x0, es_num_root_result_relations = 0,
es_tuple_routing_result_relations = 0x0, es_trig_target_relations = 0x0, es_trig_tuple_slot = 0x0,
es_trig_oldtup_slot = 0x0, es_trig_newtup_slot = 0x0, es_param_list_info = 0x0, es_param_exec_vals = 0x0,
es_queryEnv = 0x0, es_query_cxt = 0x2653e30, es_tupleTable = 0x2654af8, es_rowMarks = 0x0, es_processed = 0,
es_lastoid = 0, es_top_eflags = 16, es_instrument = 0, es_finished = false, es_exprcontexts = 0x2654550,
es_subplanstates = 0x0, es_auxmodifytables = 0x0, es_per_tuple_exprcontext = 0x0, es_epqTuple = 0x0,
es_epqTupleSet = 0x0, es_epqScanDone = 0x0, es_use_parallel_mode = false, es_query_dsa = 0x0, es_jit_flags = 0,
es_jit = 0x0, es_jit_worker_instr = 0x0}
ExecutorStart-->回到PortalStart
(gdb) n
ExecutorStart (queryDesc=0x2657f68, eflags=0) at execMain.c:148
148 }
(gdb) n
PortalStart (portal=0x25cd468, params=0x0, eflags=0, snapshot=0x0) at pquery.c:525
525 portal->queryDesc = queryDesc;
设置portal中的变量atStart等
525 portal->queryDesc = queryDesc;
(gdb) n
530 portal->tupDesc = queryDesc->tupDesc;
(gdb)
535 portal->atStart = true;
(gdb)
536 portal->atEnd = false; /* allow fetches */
(gdb)
537 portal->portalPos = 0;
(gdb)
539 PopActiveSnapshot();
(gdb)
540 break;
执行完毕,回到exec_simple_query
(gdb)
613 portal->status = PORTAL_READY;
(gdb)
614 }
(gdb)
exec_simple_query (
query_string=0x2567eb8 "select dw.*,grjf.grbh,grjf.xm,grjf.ny,grjf.je \nfrom t_dwxx dw,lateral (select gr.grbh,gr.xm,jf.ny,jf.je \n", ' ' , "from t_grxx gr inner join t_jfxx jf \n", ' ' ...) at postgres.c:1091
warning: Source file is more recent than executable.
1091 format = 0; /* TEXT is default */
(gdb)
DONE!
四、参考资料
postgres.c
PG Document:Query Planning
来自 “ ITPUB博客 ” ，链接：http://blog.itpub.net/6906/viewspace-2374807/，如需转载，请注明出处，否则将追究法律责任。
转载于:http://blog.itpub.net/6906/viewspace-2374807/