2024年9月26日: PostgreSQL 17 发布!
支持的版本:当前 (17) / 16 / 15 / 14 / 13 / 12
开发版本:devel
不支持的版本:11 / 10 / 9.6 / 9.5

59.3. 执行自定义扫描 #

当执行CustomScan时,其执行状态由CustomScanState表示,其声明如下:

typedef struct CustomScanState
{
    ScanState ss;
    uint32    flags;
    const CustomExecMethods *methods;
} CustomScanState;

ss的初始化方式与任何其他扫描状态相同,但如果扫描针对的是连接而不是基本关系,则ss.ss_currentRelation将保留为NULL。 flags是一个位掩码,其含义与CustomPathCustomScan中的相同。methods必须指向一个(通常是静态分配的)对象,该对象实现了所需的自定义扫描状态方法,这些方法将在下面详细说明。通常,CustomScanState(不需要支持copyObject)实际上是一个更大的结构,将上述结构作为其第一个成员嵌入其中。

59.3.1. 自定义扫描执行回调 #

void (*BeginCustomScan) (CustomScanState *node,
                         EState *estate,
                         int eflags);

完成提供的CustomScanState的初始化。标准字段已由ExecInitCustomScan初始化,但任何私有字段都应在此处初始化。

TupleTableSlot *(*ExecCustomScan) (CustomScanState *node);

获取下一个扫描元组。如果还有任何元组,则应使用当前扫描方向中的下一个元组填充ps_ResultTupleSlot,然后返回元组槽。如果没有,则应返回NULL或一个空槽。

void (*EndCustomScan) (CustomScanState *node);

清理与CustomScanState关联的任何私有数据。此方法是必需的,但如果没有任何关联的数据或它将自动清理,则不需要执行任何操作。

void (*ReScanCustomScan) (CustomScanState *node);

将当前扫描重绕到开头并准备重新扫描关系。

void (*MarkPosCustomScan) (CustomScanState *node);

保存当前扫描位置,以便随后可以通过RestrPosCustomScan回调恢复它。此回调是可选的,并且仅在设置了CUSTOMPATH_SUPPORT_MARK_RESTORE标志时才需要提供。

void (*RestrPosCustomScan) (CustomScanState *node);

恢复MarkPosCustomScan回调保存的先前扫描位置。此回调是可选的,并且仅在设置了CUSTOMPATH_SUPPORT_MARK_RESTORE标志时才需要提供。

Size (*EstimateDSMCustomScan) (CustomScanState *node,
                               ParallelContext *pcxt);

估计并行操作所需的动态共享内存量。这可能高于实际使用的数量,但不能低于。返回值以字节为单位。此回调是可选的,并且仅当此自定义扫描提供程序支持并行执行时才需要提供。

void (*InitializeDSMCustomScan) (CustomScanState *node,
                                 ParallelContext *pcxt,
                                 void *coordinate);

初始化并行操作所需的动态共享内存。coordinate指向一个共享内存区域,其大小等于EstimateDSMCustomScan的返回值。此回调是可选的,并且仅当此自定义扫描提供程序支持并行执行时才需要提供。

void (*ReInitializeDSMCustomScan) (CustomScanState *node,
                                   ParallelContext *pcxt,
                                   void *coordinate);

当自定义扫描计划节点即将被重新扫描时,重新初始化并行操作所需的动态共享内存。此回调是可选的,并且仅当此自定义扫描提供程序支持并行执行时才需要提供。建议的做法是,此回调仅重置共享状态,而ReScanCustomScan回调仅重置本地状态。目前,此回调将在ReScanCustomScan之前调用,但最好不要依赖此顺序。

void (*InitializeWorkerCustomScan) (CustomScanState *node,
                                    shm_toc *toc,
                                    void *coordinate);

根据领导者在InitializeDSMCustomScan期间设置的共享状态,初始化并行工作器的本地状态。此回调是可选的,并且仅当此自定义扫描提供程序支持并行执行时才需要提供。

void (*ShutdownCustomScan) (CustomScanState *node);

在预计节点不会执行到完成时释放资源。并非在所有情况下都会调用此方法;有时,可能会在未首先调用此函数的情况下调用EndCustomScan。由于并行查询使用的DSM段在此回调调用后立即被销毁,因此希望在DSM段消失之前采取某些操作的自定义扫描提供程序应实现此方法。

void (*ExplainCustomScan) (CustomScanState *node,
                           List *ancestors,
                           ExplainState *es);

为自定义扫描计划节点的EXPLAIN输出其他信息。此回调是可选的。ScanState中存储的常用数据(例如目标列表和扫描关系)即使没有此回调也会显示,但回调允许显示其他私有状态。

提交更正

如果您在文档中发现任何不正确的内容、与您对特定功能的体验不符的内容或需要进一步澄清的内容,请使用此表单报告文档问题。