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

   1
   2 60.2. Creating Custom Scan Plans #
   3
   4    60.2.1. Custom Scan Plan Callbacks
   5
   6    A custom scan is represented in a finished plan tree using the
   7    following structure:
   8 typedef struct CustomScan
   9 {
  10     Scan      scan;
  11     uint32    flags;
  12     List     *custom_plans;
  13     List     *custom_exprs;
  14     List     *custom_private;
  15     List     *custom_scan_tlist;
  16     Bitmapset *custom_relids;
  17     const CustomScanMethods *methods;
  18 } CustomScan;
  19
  20    scan must be initialized as for any other scan, including estimated
  21    costs, target lists, qualifications, and so on. flags is a bit mask
  22    with the same meaning as in CustomPath. custom_plans can be used to
  23    store child Plan nodes. custom_exprs should be used to store expression
  24    trees that will need to be fixed up by setrefs.c and subselect.c, while
  25    custom_private should be used to store other private data that is only
  26    used by the custom scan provider itself. custom_scan_tlist can be NIL
  27    when scanning a base relation, indicating that the custom scan returns
  28    scan tuples that match the base relation's row type. Otherwise it is a
  29    target list describing the actual scan tuples. custom_scan_tlist must
  30    be provided for joins, and could be provided for scans if the custom
  31    scan provider can compute some non-Var expressions. custom_relids is
  32    set by the core code to the set of relations (range table indexes) that
  33    this scan node handles; except when this scan is replacing a join, it
  34    will have only one member. methods must point to a (usually statically
  35    allocated) object implementing the required custom scan methods, which
  36    are further detailed below.
  37
  38    When a CustomScan scans a single relation, scan.scanrelid must be the
  39    range table index of the table to be scanned. When it replaces a join,
  40    scan.scanrelid should be zero.
  41
  42    Plan trees must be able to be duplicated using copyObject, so all the
  43    data stored within the “custom” fields must consist of nodes that that
  44    function can handle. Furthermore, custom scan providers cannot
  45    substitute a larger structure that embeds a CustomScan for the
  46    structure itself, as would be possible for a CustomPath or
  47    CustomScanState.
  48
  49 60.2.1. Custom Scan Plan Callbacks #
  50
  51 Node *(*CreateCustomScanState) (CustomScan *cscan);
  52
  53    Allocate a CustomScanState for this CustomScan. The actual allocation
  54    will often be larger than required for an ordinary CustomScanState,
  55    because many providers will wish to embed that as the first field of a
  56    larger structure. The value returned must have the node tag and methods
  57    set appropriately, but other fields should be left as zeroes at this
  58    stage; after ExecInitCustomScan performs basic initialization, the
  59    BeginCustomScan callback will be invoked to give the custom scan
  60    provider a chance to do whatever else is needed.