Custom Scans</title>

  <para>
   When a <structfield>CustomScan</structfield> is executed, its execution state is
   represented by a <structfield>CustomScanState</structfield>, which is declared as
   follows:
<programlisting>
typedef struct CustomScanState
{
    ScanState ss;
    uint32    flags;
    const CustomExecMethods *methods;
} CustomScanState;
</programlisting>
  </para>

  <para>
   <structfield>ss</structfield> is initialized as for any other scan state,
   except that if the scan is for a join rather than a base relation,
   <literal>ss.ss_currentRelation</literal> is left NULL.
   <structfield>flags</structfield> is a bit mask with the same meaning as in
   <structname>CustomPath</structname> and <structname>CustomScan</structname>.
   <structfield>methods</structfield> must point to a (usually statically allocated)
   object implementing the required custom scan state methods, which are
   further detailed below.  Typically, a <structname>CustomScanState</structname>, which
   need not support <function>copyObject</function>, will actually be a larger
   structure embedding the above as its first member.
  </para>

  <sect2 id="custom-scan-execution-callbacks">
   <title>Custom Scan Execution Callbacks</title>

   <para>
<programlisting>
void (*BeginCustomScan) (CustomScanState *node,
                         EState *estate,
                         int eflags);
</programlisting>
    Complete initialization of the supplied <structname>CustomScanState</structname>.
    Standard fields have been initialized by <function>ExecInitCustomScan</function>,
    but any private fields should be initialized here.
   </para>

   <para>
<programlisting>
TupleTableSlot *(*ExecCustomScan) (CustomScanState *node);
</programlisting>
    Fetch the next scan tuple.  If any tuples remain, it should fill
    <literal>ps_ResultTupleSlot</literal> with the next tuple in the current scan
    direction, and then return the tuple slot.  If not,
    <literal>NULL</literal> or an empty slot should be returned.
   </para>

   <para>
<programlisting>
void (*EndCustomScan) (CustomScanState *node);
</programlisting>
    Clean up any private data associated with the <literal>CustomScanState</literal>.
    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.
   </para>

   <para>
<programlisting>
void (*ReScanCustomScan) (CustomScanState *node);
</programlisting>
    Rewind the current scan to the beginning and prepare to rescan the
    relation.
   </para>

   <para>
<programlisting>
void (*MarkPosCustomScan) (CustomScanState *node);
</programlisting>
    Save the current scan position so that it can subsequently be restored
    by the <function>RestrPosCustomScan</function> callback.  This callback is
    optional, and need only be supplied if the
    <literal>CUSTOMPATH_SUPPORT_MARK_RESTORE</literal> flag is set.
   </para>

   <para>
<programlisting>
void (*RestrPosCustomScan) (CustomScanState *node);
</programlisting>
    Restore the previous scan position as saved by the
    <function>MarkPosCustomScan</function> callback.  This callback is optional,
    and need only be supplied if the
    <literal>CUSTOMPATH_SUPPORT_MARK_RESTORE</literal> flag is set.
   </para>

   <para>
<programlisting>
Size (*EstimateDSMCustomScan) (CustomScanState *node,