2025年9月25日: PostgreSQL 18 釋出!
支援的版本: 當前 (18) / 17 / 16 / 15 / 14 / 13
開發版本: devel
不支援的版本: 12 / 11 / 10 / 9.6 / 9.5

60.3. 執行自定義掃描 #

當執行 CustomScan 時,其執行狀態由 CustomScanState 表示,該結構宣告如下:

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

ss 的初始化與其他任何掃描狀態一樣,只是如果掃描是為了連線而不是基表,則 ss.ss_currentRelation 將保持為 NULL。 flags 是一個位掩碼,其含義與 CustomPathCustomScan 中的相同。 methods 必須指向一個(通常是靜態分配的)實現了所需自定義掃描狀態方法的物件,這些方法將在下面進一步詳細介紹。通常,一個 CustomScanState(不需要支援 copyObject)實際上是一個更大的結構,它將上述結構作為其第一個成員嵌入。

60.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 中儲存的常用資料,如目標列表和掃描關係,即使沒有此回撥也會顯示,但該回調允許顯示額外的私有狀態。

提交更正

如果您在文件中看到任何不正確、與您在使用特定功能時的體驗不符或需要進一步澄清的內容,請使用此表單報告文件問題。