Executing Custom Scans

PostgreSQL 9.5.3 Documentation
Prev | Up | Chapter 56. Writing A Custom Scan Provider | Next

# 56.3. Executing Custom Scans

When a `CustomScan` is executed, its execution state is represented by a `CustomScanState`, 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 in `CustomPath` and `CustomScan`. `methods` must point to a (usually statically allocated) object implementing the required custom scan state methods, which are further detailed below. Typically, a `CustomScanState`, which need not support `copyObject`, will actually be a larger structure embedding the above as its first member.

## 56.3.1. Custom Scan Execution Callbacks

    void (*BeginCustomScan) (CustomScanState *node,
                             EState *estate,
                             int eflags);

Complete initialization of the supplied `CustomScanState`. Standard fields have been initialized by `ExecInitCustomScan`, but any private fields should be initialized here.

    TupleTableSlot *(*ExecCustomScan) (CustomScanState *node);

Fetch the next scan tuple. If any tuples remain, it should fill `ps_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 the `CustomScanState`. 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 the `RestrPosCustomScan` callback. This callback is optional, and need only be supplied if the `CUSTOMPATH_SUPPORT_MARK_RESTORE` flag is set.

    void (*RestrPosCustomScan) (CustomScanState *node);

Restore the previous scan position as saved by the `MarkPosCustomScan` callback. This callback is optional, and need only be supplied if the `CUSTOMPATH_SUPPORT_MARK_RESTORE` flag is set.

    void (*ExplainCustomScan) (CustomScanState *node,
                               List *ancestors,
                               ExplainState *es);

Output additional information for `EXPLAIN` of a custom-scan plan node. This callback is optional. Common data stored in the `ScanState`, 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.

Prev | Home | Next
Creating Custom Scan Plans | Up | Genetic Query Optimizer