diff options
Diffstat (limited to 'doc/src/sgml/html/custom-scan-execution.html')
| -rw-r--r-- | doc/src/sgml/html/custom-scan-execution.html | 139 |
1 files changed, 139 insertions, 0 deletions
diff --git a/doc/src/sgml/html/custom-scan-execution.html b/doc/src/sgml/html/custom-scan-execution.html new file mode 100644 index 0000000..9a32f38 --- /dev/null +++ b/doc/src/sgml/html/custom-scan-execution.html @@ -0,0 +1,139 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!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>61.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="61.2. Creating Custom Scan Plans" /><link rel="next" href="geqo.html" title="Chapter 62. 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">61.3. Executing Custom Scans</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="custom-scan-plan.html" title="61.2. Creating Custom Scan Plans">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="custom-scan.html" title="Chapter 61. Writing a Custom Scan Provider">Up</a></td><th width="60%" align="center">Chapter 61. Writing a Custom Scan Provider</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="geqo.html" title="Chapter 62. 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">61.3. Executing Custom Scans</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="custom-scan-execution.html#CUSTOM-SCAN-EXECUTION-CALLBACKS">61.3.1. Custom Scan Execution Callbacks</a></span></dt></dl></div><p> + When a <code class="structfield">CustomScan</code> is executed, its execution state is + represented by a <code class="structfield">CustomScanState</code>, which is declared as + follows: +</p><pre class="programlisting"> +typedef struct CustomScanState +{ + ScanState ss; + uint32 flags; + const CustomExecMethods *methods; +} CustomScanState; +</pre><p> + </p><p> + <code class="structfield">ss</code> is initialized as for any other scan state, + except that if the scan is for a join rather than a base relation, + <code class="literal">ss.ss_currentRelation</code> is left NULL. + <code class="structfield">flags</code> is a bit mask with the same meaning as in + <code class="structname">CustomPath</code> and <code class="structname">CustomScan</code>. + <code class="structfield">methods</code> must point to a (usually statically allocated) + object implementing the required custom scan state methods, which are + further detailed below. Typically, a <code class="structname">CustomScanState</code>, which + need not support <code class="function">copyObject</code>, will actually be a larger + structure embedding the above as its first member. + </p><div class="sect2" id="CUSTOM-SCAN-EXECUTION-CALLBACKS"><div class="titlepage"><div><div><h3 class="title">61.3.1. Custom Scan Execution Callbacks</h3></div></div></div><p> +</p><pre class="programlisting"> +void (*BeginCustomScan) (CustomScanState *node, + EState *estate, + int eflags); +</pre><p> + Complete initialization of the supplied <code class="structname">CustomScanState</code>. + Standard fields have been initialized by <code class="function">ExecInitCustomScan</code>, + but any private fields should be initialized here. + </p><p> +</p><pre class="programlisting"> +TupleTableSlot *(*ExecCustomScan) (CustomScanState *node); +</pre><p> + Fetch the next scan tuple. If any tuples remain, it should fill + <code class="literal">ps_ResultTupleSlot</code> with the next tuple in the current scan + direction, and then return the tuple slot. If not, + <code class="literal">NULL</code> or an empty slot should be returned. + </p><p> +</p><pre class="programlisting"> +void (*EndCustomScan) (CustomScanState *node); +</pre><p> + Clean up any private data associated with the <code class="literal">CustomScanState</code>. + 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. + </p><p> +</p><pre class="programlisting"> +void (*ReScanCustomScan) (CustomScanState *node); +</pre><p> + Rewind the current scan to the beginning and prepare to rescan the + relation. + </p><p> +</p><pre class="programlisting"> +void (*MarkPosCustomScan) (CustomScanState *node); +</pre><p> + Save the current scan position so that it can subsequently be restored + by the <code class="function">RestrPosCustomScan</code> callback. This callback is + optional, and need only be supplied if the + <code class="literal">CUSTOMPATH_SUPPORT_MARK_RESTORE</code> flag is set. + </p><p> +</p><pre class="programlisting"> +void (*RestrPosCustomScan) (CustomScanState *node); +</pre><p> + Restore the previous scan position as saved by the + <code class="function">MarkPosCustomScan</code> callback. This callback is optional, + and need only be supplied if the + <code class="literal">CUSTOMPATH_SUPPORT_MARK_RESTORE</code> flag is set. + </p><p> +</p><pre class="programlisting"> +Size (*EstimateDSMCustomScan) (CustomScanState *node, + ParallelContext *pcxt); +</pre><p> + Estimate the amount of dynamic shared memory that will be required + for parallel operation. This may be higher than the amount that will + actually be used, but it must not be lower. The return value is in bytes. + This callback is optional, and need only be supplied if this custom + scan provider supports parallel execution. + </p><p> +</p><pre class="programlisting"> +void (*InitializeDSMCustomScan) (CustomScanState *node, + ParallelContext *pcxt, + void *coordinate); +</pre><p> + Initialize the dynamic shared memory that will be required for parallel + operation. <code class="literal">coordinate</code> points to a shared memory area of + size equal to the return value of <code class="function">EstimateDSMCustomScan</code>. + This callback is optional, and need only be supplied if this custom + scan provider supports parallel execution. + </p><p> +</p><pre class="programlisting"> +void (*ReInitializeDSMCustomScan) (CustomScanState *node, + ParallelContext *pcxt, + void *coordinate); +</pre><p> + Re-initialize the dynamic shared memory required for parallel operation + when the custom-scan plan node is about to be re-scanned. + This callback is optional, and need only be supplied if this custom + scan provider supports parallel execution. + Recommended practice is that this callback reset only shared state, + while the <code class="function">ReScanCustomScan</code> callback resets only local + state. Currently, this callback will be called + before <code class="function">ReScanCustomScan</code>, but it's best not to rely on + that ordering. + </p><p> +</p><pre class="programlisting"> +void (*InitializeWorkerCustomScan) (CustomScanState *node, + shm_toc *toc, + void *coordinate); +</pre><p> + Initialize a parallel worker's local state based on the shared state + set up by the leader during <code class="function">InitializeDSMCustomScan</code>. + This callback is optional, and need only be supplied if this custom + scan provider supports parallel execution. + </p><p> +</p><pre class="programlisting"> +void (*ShutdownCustomScan) (CustomScanState *node); +</pre><p> + Release resources when it is anticipated the node will not be executed + to completion. This is not called in all cases; sometimes, + <code class="literal">EndCustomScan</code> may be called without this function having + been called first. Since the DSM segment used by parallel query is + destroyed just after this callback is invoked, custom scan providers that + wish to take some action before the DSM segment goes away should implement + this method. + </p><p> +</p><pre class="programlisting"> +void (*ExplainCustomScan) (CustomScanState *node, + List *ancestors, + ExplainState *es); +</pre><p> + Output additional information for <code class="command">EXPLAIN</code> of a custom-scan + plan node. This callback is optional. Common data stored in the + <code class="structname">ScanState</code>, 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. + </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="61.2. Creating Custom Scan Plans">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="custom-scan.html" title="Chapter 61. Writing a Custom Scan Provider">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="geqo.html" title="Chapter 62. Genetic Query Optimizer">Next</a></td></tr><tr><td width="40%" align="left" valign="top">61.2. Creating Custom Scan Plans </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 62. Genetic Query Optimizer</td></tr></table></div></body></html>
\ No newline at end of file |