begriffs open source - ai-pg/blob - full-docs/src/sgml/html/custom-scan-execution.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>60.3. Executing Custom Scans</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="custom-scan-plan.html" title="60.2. Creating Custom Scan Plans" /><link rel="next" href="geqo.html" title="Chapter 61. Genetic Query Optimizer" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">60.3. Executing Custom Scans</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="custom-scan-plan.html" title="60.2. Creating Custom Scan Plans">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="custom-scan.html" title="Chapter 60. Writing a Custom Scan Provider">Up</a></td><th width="60%" align="center">Chapter 60. Writing a Custom Scan Provider</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="geqo.html" title="Chapter 61. Genetic Query Optimizer">Next</a></td></tr></table><hr /></div><div class="sect1" id="CUSTOM-SCAN-EXECUTION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">60.3. Executing Custom Scans <a href="#CUSTOM-SCAN-EXECUTION" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="custom-scan-execution.html#CUSTOM-SCAN-EXECUTION-CALLBACKS">60.3.1. Custom Scan Execution Callbacks</a></span></dt></dl></div><p>
   3    When a <code class="structfield">CustomScan</code> is executed, its execution state is
   4    represented by a <code class="structfield">CustomScanState</code>, which is declared as
   5    follows:
   6 </p><pre class="programlisting">
   7 typedef struct CustomScanState
   8 {
   9     ScanState ss;
  10     uint32    flags;
  11     const CustomExecMethods *methods;
  12 } CustomScanState;
  13 </pre><p>
  14   </p><p>
  15    <code class="structfield">ss</code> is initialized as for any other scan state,
  16    except that if the scan is for a join rather than a base relation,
  17    <code class="literal">ss.ss_currentRelation</code> is left NULL.
  18    <code class="structfield">flags</code> is a bit mask with the same meaning as in
  19    <code class="structname">CustomPath</code> and <code class="structname">CustomScan</code>.
  20    <code class="structfield">methods</code> must point to a (usually statically allocated)
  21    object implementing the required custom scan state methods, which are
  22    further detailed below.  Typically, a <code class="structname">CustomScanState</code>, which
  23    need not support <code class="function">copyObject</code>, will actually be a larger
  24    structure embedding the above as its first member.
  25   </p><div class="sect2" id="CUSTOM-SCAN-EXECUTION-CALLBACKS"><div class="titlepage"><div><div><h3 class="title">60.3.1. Custom Scan Execution Callbacks <a href="#CUSTOM-SCAN-EXECUTION-CALLBACKS" class="id_link">#</a></h3></div></div></div><p>
  26 </p><pre class="programlisting">
  27 void (*BeginCustomScan) (CustomScanState *node,
  28                          EState *estate,
  29                          int eflags);
  30 </pre><p>
  31     Complete initialization of the supplied <code class="structname">CustomScanState</code>.
  32     Standard fields have been initialized by <code class="function">ExecInitCustomScan</code>,
  33     but any private fields should be initialized here.
  34    </p><p>
  35 </p><pre class="programlisting">
  36 TupleTableSlot *(*ExecCustomScan) (CustomScanState *node);
  37 </pre><p>
  38     Fetch the next scan tuple.  If any tuples remain, it should fill
  39     <code class="literal">ps_ResultTupleSlot</code> with the next tuple in the current scan
  40     direction, and then return the tuple slot.  If not,
  41     <code class="literal">NULL</code> or an empty slot should be returned.
  42    </p><p>
  43 </p><pre class="programlisting">
  44 void (*EndCustomScan) (CustomScanState *node);
  45 </pre><p>
  46     Clean up any private data associated with the <code class="literal">CustomScanState</code>.
  47     This method is required, but it does not need to do anything if there is
  48     no associated data or it will be cleaned up automatically.
  49    </p><p>
  50 </p><pre class="programlisting">
  51 void (*ReScanCustomScan) (CustomScanState *node);
  52 </pre><p>
  53     Rewind the current scan to the beginning and prepare to rescan the
  54     relation.
  55    </p><p>
  56 </p><pre class="programlisting">
  57 void (*MarkPosCustomScan) (CustomScanState *node);
  58 </pre><p>
  59     Save the current scan position so that it can subsequently be restored
  60     by the <code class="function">RestrPosCustomScan</code> callback.  This callback is
  61     optional, and need only be supplied if the
  62     <code class="literal">CUSTOMPATH_SUPPORT_MARK_RESTORE</code> flag is set.
  63    </p><p>
  64 </p><pre class="programlisting">
  65 void (*RestrPosCustomScan) (CustomScanState *node);
  66 </pre><p>
  67     Restore the previous scan position as saved by the
  68     <code class="function">MarkPosCustomScan</code> callback.  This callback is optional,
  69     and need only be supplied if the
  70     <code class="literal">CUSTOMPATH_SUPPORT_MARK_RESTORE</code> flag is set.
  71    </p><p>
  72 </p><pre class="programlisting">
  73 Size (*EstimateDSMCustomScan) (CustomScanState *node,
  74                                ParallelContext *pcxt);
  75 </pre><p>
  76     Estimate the amount of dynamic shared memory that will be required
  77     for parallel operation.  This may be higher than the amount that will
  78     actually be used, but it must not be lower.  The return value is in bytes.
  79     This callback is optional, and need only be supplied if this custom
  80     scan provider supports parallel execution.
  81    </p><p>
  82 </p><pre class="programlisting">
  83 void (*InitializeDSMCustomScan) (CustomScanState *node,
  84                                  ParallelContext *pcxt,
  85                                  void *coordinate);
  86 </pre><p>
  87     Initialize the dynamic shared memory that will be required for parallel
  88     operation.  <code class="literal">coordinate</code> points to a shared memory area of
  89     size equal to the return value of <code class="function">EstimateDSMCustomScan</code>.
  90     This callback is optional, and need only be supplied if this custom
  91     scan provider supports parallel execution.
  92    </p><p>
  93 </p><pre class="programlisting">
  94 void (*ReInitializeDSMCustomScan) (CustomScanState *node,
  95                                    ParallelContext *pcxt,
  96                                    void *coordinate);
  97 </pre><p>
  98     Re-initialize the dynamic shared memory required for parallel operation
  99     when the custom-scan plan node is about to be re-scanned.
 100     This callback is optional, and need only be supplied if this custom
 101     scan provider supports parallel execution.
 102     Recommended practice is that this callback reset only shared state,
 103     while the <code class="function">ReScanCustomScan</code> callback resets only local
 104     state.  Currently, this callback will be called
 105     before <code class="function">ReScanCustomScan</code>, but it's best not to rely on
 106     that ordering.
 107    </p><p>
 108 </p><pre class="programlisting">
 109 void (*InitializeWorkerCustomScan) (CustomScanState *node,
 110                                     shm_toc *toc,
 111                                     void *coordinate);
 112 </pre><p>
 113     Initialize a parallel worker's local state based on the shared state
 114     set up by the leader during <code class="function">InitializeDSMCustomScan</code>.
 115     This callback is optional, and need only be supplied if this custom
 116     scan provider supports parallel execution.
 117    </p><p>
 118 </p><pre class="programlisting">
 119 void (*ShutdownCustomScan) (CustomScanState *node);
 120 </pre><p>
 121     Release resources when it is anticipated the node will not be executed
 122     to completion.  This is not called in all cases; sometimes,
 123     <code class="literal">EndCustomScan</code> may be called without this function having
 124     been called first.  Since the DSM segment used by parallel query is
 125     destroyed just after this callback is invoked, custom scan providers that
 126     wish to take some action before the DSM segment goes away should implement
 127     this method.
 128    </p><p>
 129 </p><pre class="programlisting">
 130 void (*ExplainCustomScan) (CustomScanState *node,
 131                            List *ancestors,
 132                            ExplainState *es);
 133 </pre><p>
 134     Output additional information for <code class="command">EXPLAIN</code> of a custom-scan
 135     plan node.  This callback is optional.  Common data stored in the
 136     <code class="structname">ScanState</code>, such as the target list and scan relation, will
 137     be shown even without this callback, but the callback allows the display
 138     of additional, private state.
 139    </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="custom-scan-plan.html" title="60.2. Creating Custom Scan Plans">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="custom-scan.html" title="Chapter 60. Writing a Custom Scan Provider">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="geqo.html" title="Chapter 61. Genetic Query Optimizer">Next</a></td></tr><tr><td width="40%" align="left" valign="top">60.2. Creating Custom Scan Plans </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 61. Genetic Query Optimizer</td></tr></table></div></body></html>