begriffs open source - ai-pg/blob - full-docs/txt/custom-scan-execution.txt

   1
   2 60.3. Executing Custom Scans #
   3
   4    60.3.1. Custom Scan Execution Callbacks
   5
   6    When a CustomScan is executed, its execution state is represented by a
   7    CustomScanState, which is declared as follows:
   8 typedef struct CustomScanState
   9 {
  10     ScanState ss;
  11     uint32    flags;
  12     const CustomExecMethods *methods;
  13 } CustomScanState;
  14
  15    ss is initialized as for any other scan state, except that if the scan
  16    is for a join rather than a base relation, ss.ss_currentRelation is
  17    left NULL. flags is a bit mask with the same meaning as in CustomPath
  18    and CustomScan. methods must point to a (usually statically allocated)
  19    object implementing the required custom scan state methods, which are
  20    further detailed below. Typically, a CustomScanState, which need not
  21    support copyObject, will actually be a larger structure embedding the
  22    above as its first member.
  23
  24 60.3.1. Custom Scan Execution Callbacks #
  25
  26 void (*BeginCustomScan) (CustomScanState *node,
  27                          EState *estate,
  28                          int eflags);
  29
  30    Complete initialization of the supplied CustomScanState. Standard
  31    fields have been initialized by ExecInitCustomScan, but any private
  32    fields should be initialized here.
  33
  34 TupleTableSlot *(*ExecCustomScan) (CustomScanState *node);
  35
  36    Fetch the next scan tuple. If any tuples remain, it should fill
  37    ps_ResultTupleSlot with the next tuple in the current scan direction,
  38    and then return the tuple slot. If not, NULL or an empty slot should be
  39    returned.
  40
  41 void (*EndCustomScan) (CustomScanState *node);
  42
  43    Clean up any private data associated with the CustomScanState. This
  44    method is required, but it does not need to do anything if there is no
  45    associated data or it will be cleaned up automatically.
  46
  47 void (*ReScanCustomScan) (CustomScanState *node);
  48
  49    Rewind the current scan to the beginning and prepare to rescan the
  50    relation.
  51
  52 void (*MarkPosCustomScan) (CustomScanState *node);
  53
  54    Save the current scan position so that it can subsequently be restored
  55    by the RestrPosCustomScan callback. This callback is optional, and need
  56    only be supplied if the CUSTOMPATH_SUPPORT_MARK_RESTORE flag is set.
  57
  58 void (*RestrPosCustomScan) (CustomScanState *node);
  59
  60    Restore the previous scan position as saved by the MarkPosCustomScan
  61    callback. This callback is optional, and need only be supplied if the
  62    CUSTOMPATH_SUPPORT_MARK_RESTORE flag is set.
  63
  64 Size (*EstimateDSMCustomScan) (CustomScanState *node,
  65                                ParallelContext *pcxt);
  66
  67    Estimate the amount of dynamic shared memory that will be required for
  68    parallel operation. This may be higher than the amount that will
  69    actually be used, but it must not be lower. The return value is in
  70    bytes. This callback is optional, and need only be supplied if this
  71    custom scan provider supports parallel execution.
  72
  73 void (*InitializeDSMCustomScan) (CustomScanState *node,
  74                                  ParallelContext *pcxt,
  75                                  void *coordinate);
  76
  77    Initialize the dynamic shared memory that will be required for parallel
  78    operation. coordinate points to a shared memory area of size equal to
  79    the return value of EstimateDSMCustomScan. This callback is optional,
  80    and need only be supplied if this custom scan provider supports
  81    parallel execution.
  82
  83 void (*ReInitializeDSMCustomScan) (CustomScanState *node,
  84                                    ParallelContext *pcxt,
  85                                    void *coordinate);
  86
  87    Re-initialize the dynamic shared memory required for parallel operation
  88    when the custom-scan plan node is about to be re-scanned. This callback
  89    is optional, and need only be supplied if this custom scan provider
  90    supports parallel execution. Recommended practice is that this callback
  91    reset only shared state, while the ReScanCustomScan callback resets
  92    only local state. Currently, this callback will be called before
  93    ReScanCustomScan, but it's best not to rely on that ordering.
  94
  95 void (*InitializeWorkerCustomScan) (CustomScanState *node,
  96                                     shm_toc *toc,
  97                                     void *coordinate);
  98
  99    Initialize a parallel worker's local state based on the shared state
 100    set up by the leader during InitializeDSMCustomScan. This callback is
 101    optional, and need only be supplied if this custom scan provider
 102    supports parallel execution.
 103
 104 void (*ShutdownCustomScan) (CustomScanState *node);
 105
 106    Release resources when it is anticipated the node will not be executed
 107    to completion. This is not called in all cases; sometimes,
 108    EndCustomScan may be called without this function having been called
 109    first. Since the DSM segment used by parallel query is destroyed just
 110    after this callback is invoked, custom scan providers that wish to take
 111    some action before the DSM segment goes away should implement this
 112    method.
 113
 114 void (*ExplainCustomScan) (CustomScanState *node,
 115                            List *ancestors,
 116                            ExplainState *es);
 117
 118    Output additional information for EXPLAIN of a custom-scan plan node.
 119    This callback is optional. Common data stored in the ScanState, such as
 120    the target list and scan relation, will be shown even without this
 121    callback, but the callback allows the display of additional, private
 122    state.