57.3. Executing Custom Scans
When aCustomScan is executed, its execution state is represented by aCustomScanState, which is declared as follows:
typedef struct CustomScanState{ ScanState ss; uint32 flags; const CustomExecMethods *methods;} CustomScanState;ss is initialized as for any other scan state, except that if the scan is for a join rather than a base relation,ss.ss_currentRelation is left NULL.flags is a bit mask with the same meaning as inCustomPath andCustomScan.methods must point to a (usually statically allocated) object implementing the required custom scan state methods, which are further detailed below. Typically, aCustomScanState, which need not supportcopyObject, will actually be a larger structure embedding the above as its first member.
57.3.1. Custom Scan Execution Callbacks
void (*BeginCustomScan) (CustomScanState *node, EState *estate, int eflags);
Complete initialization of the suppliedCustomScanState. Standard fields have been initialized byExecInitCustomScan, but any private fields should be initialized here.
TupleTableSlot *(*ExecCustomScan) (CustomScanState *node);
Fetch the next scan tuple. If any tuples remain, it should fillps_ResultTupleSlot with the next tuple in the current scan direction, and then return the tuple slot. If not,NULL or an empty slot should be returned.
void (*EndCustomScan) (CustomScanState *node);
Clean up any private data associated with theCustomScanState. This method is required, but it does not need to do anything if there is no associated data or it will be cleaned up automatically.
void (*ReScanCustomScan) (CustomScanState *node);
Rewind the current scan to the beginning and prepare to rescan the relation.
void (*MarkPosCustomScan) (CustomScanState *node);
Save the current scan position so that it can subsequently be restored by theRestrPosCustomScan callback. This callback is optional, and need only be supplied if theCUSTOMPATH_SUPPORT_MARK_RESTORE flag is set.
void (*RestrPosCustomScan) (CustomScanState *node);
Restore the previous scan position as saved by theMarkPosCustomScan callback. This callback is optional, and need only be supplied if theCUSTOMPATH_SUPPORT_MARK_RESTORE flag is set.
Size (*EstimateDSMCustomScan) (CustomScanState *node, ParallelContext *pcxt);
Estimate the amount of dynamic shared memory that will be required for parallel operation. This may be higher than the amount that will actually be used, but it must not be lower. The return value is in bytes. This callback is optional, and need only be supplied if this custom scan provider supports parallel execution.
void (*InitializeDSMCustomScan) (CustomScanState *node, ParallelContext *pcxt, void *coordinate);
Initialize the dynamic shared memory that will be required for parallel operation;coordinate points to an amount of allocated space equal to the return value ofEstimateDSMCustomScan. This callback is optional, and need only be supplied if this custom scan provider supports parallel execution.
void (*InitializeWorkerCustomScan) (CustomScanState *node, shm_toc *toc, void *coordinate);
Initialize a parallel worker's custom state based on the shared state set up in the leader byInitializeDSMCustomScan. This callback is optional, and needs only be supplied if this custom path supports parallel execution.
void (*ExplainCustomScan) (CustomScanState *node, List *ancestors, ExplainState *es);
Output additional information forEXPLAIN of a custom-scan plan node. This callback is optional. Common data stored in theScanState, such as the target list and scan relation, will be shown even without this callback, but the callback allows the display of additional, private state.