Redrock Postgres 搜索 英文
版本: 9.5 / 9.6 / 10 / 11 / 12 / 13 / 14 / 15 / 16 / 17

59.3. 执行自定义扫描 #

59.3.1. 自定义扫描执行回调

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

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

ss 初始化如同任何其他扫描状态,但如果扫描是针对关联关系而不是基本关系,则 ss.ss_currentRelation 留空。 flags 是一个比特掩码,具有与 CustomPathCustomScan 中相同的含义。 methods 必须指向一个实现所需自定义扫描状态方法的 (通常静态分配的) 对象,这些方法在下面进一步详细介绍。通常,不需要支持 copyObjectCustomScanState 实际上是一个包含上述内容作为其第一个成员的更大结构。

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 中存储的常用数据(例如目标列表和扫描关系)即使没有此回调也会显示,但回调允许显示其他私有状态。