Postgresql 中文操作指南

61.3. Executing Custom Scans #

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

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

ss 初始化为任何其他扫描状态，但如果扫描是用于联接而不是基本关系，则 ss.ss_currentRelation 保留为 NULL。flags 是与 CustomPath 和 CustomScan 中含义相同的位掩码。methods 必须指向一个（通常是静态分配的）对象，该对象实现了必需的自定义扫描状态方法，如下详述。通常，CustomScanState （不需要支持 copyObject）实际上将作为其第一个成员嵌入上述内容的一个更大结构。

61.3.1. Custom Scan Execution Callbacks #

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 中的常用数据（例如目标列表和扫描关系）即使没有此回调也会显示，但此回调可以显示其他私有状态。