granicus.if.org Git - postgresql/blob - src/include/utils/portal.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * portal.h
   4  *        POSTGRES portal definitions.
   5  *
   6  * A portal is an abstraction which represents the execution state of
   7  * a running or runnable query.  Portals support both SQL-level CURSORs
   8  * and protocol-level portals.
   9  *
  10  * Scrolling (nonsequential access) and suspension of execution are allowed
  11  * only for portals that contain a single SELECT-type query.  We do not want
  12  * to let the client suspend an update-type query partway through!      Because
  13  * the query rewriter does not allow arbitrary ON SELECT rewrite rules,
  14  * only queries that were originally update-type could produce multiple
  15  * parse/plan trees; so the restriction to a single query is not a problem
  16  * in practice.
  17  *
  18  * For SQL cursors, we support three kinds of scroll behavior:
  19  *
  20  * (1) Neither NO SCROLL nor SCROLL was specified: to remain backward
  21  *         compatible, we allow backward fetches here, unless it would
  22  *         impose additional runtime overhead to do so.
  23  *
  24  * (2) NO SCROLL was specified: don't allow any backward fetches.
  25  *
  26  * (3) SCROLL was specified: allow all kinds of backward fetches, even
  27  *         if we need to take a performance hit to do so.  (The planner sticks
  28  *         a Materialize node atop the query plan if needed.)
  29  *
  30  * Case #1 is converted to #2 or #3 by looking at the query itself and
  31  * determining if scrollability can be supported without additional
  32  * overhead.
  33  *
  34  * Protocol-level portals have no nonsequential-fetch API and so the
  35  * distinction doesn't matter for them.  They are always initialized
  36  * to look like NO SCROLL cursors.
  37  *
  38  *
  39  * Portions Copyright (c) 1996-2003, PostgreSQL Global Development Group
  40  * Portions Copyright (c) 1994, Regents of the University of California
  41  *
  42  * $Id: portal.h,v 1.47 2003/08/08 21:42:55 momjian Exp $
  43  *
  44  *-------------------------------------------------------------------------
  45  */
  46 #ifndef PORTAL_H
  47 #define PORTAL_H
  48
  49 #include "executor/execdesc.h"
  50 #include "nodes/memnodes.h"
  51 #include "utils/tuplestore.h"
  52
  53
  54 /*
  55  * We have several execution strategies for Portals, depending on what
  56  * query or queries are to be executed.  (Note: in all cases, a Portal
  57  * executes just a single source-SQL query, and thus produces just a
  58  * single result from the user's viewpoint.  However, the rule rewriter
  59  * may expand the single source query to zero or many actual queries.)
  60  *
  61  * PORTAL_ONE_SELECT: the portal contains one single SELECT query.      We run
  62  * the Executor incrementally as results are demanded.  This strategy also
  63  * supports holdable cursors (the Executor results can be dumped into a
  64  * tuplestore for access after transaction completion).
  65  *
  66  * PORTAL_UTIL_SELECT: the portal contains a utility statement that returns
  67  * a SELECT-like result (for example, EXPLAIN or SHOW).  On first execution,
  68  * we run the statement and dump its results into the portal tuplestore;
  69  * the results are then returned to the client as demanded.
  70  *
  71  * PORTAL_MULTI_QUERY: all other cases.  Here, we do not support partial
  72  * execution: the portal's queries will be run to completion on first call.
  73  */
  74
  75 typedef enum PortalStrategy
  76 {
  77         PORTAL_ONE_SELECT,
  78         PORTAL_UTIL_SELECT,
  79         PORTAL_MULTI_QUERY
  80 } PortalStrategy;
  81
  82 /*
  83  * Note: typedef Portal is declared in tcop/dest.h as
  84  *              typedef struct PortalData *Portal;
  85  */
  86
  87 typedef struct PortalData
  88 {
  89         /* Bookkeeping data */
  90         const char *name;                       /* portal's name */
  91         MemoryContext heap;                     /* subsidiary memory for portal */
  92         void            (*cleanup) (Portal portal, bool isError);               /* cleanup hook */
  93         TransactionId createXact;       /* the xid of the creating xact */
  94
  95         /* The query or queries the portal will execute */
  96         const char *sourceText;         /* text of query, if known (may be NULL) */
  97         const char *commandTag;         /* command tag for original query */
  98         List       *parseTrees;         /* parse tree(s) */
  99         List       *planTrees;          /* plan tree(s) */
 100         MemoryContext queryContext; /* where the above trees live */
 101
 102         /*
 103          * Note: queryContext effectively identifies which prepared statement
 104          * the portal depends on, if any.  The queryContext is *not* owned by
 105          * the portal and is not to be deleted by portal destruction.  (But
 106          * for a cursor it is the same as "heap", and that context is deleted
 107          * by portal destruction.)
 108          */
 109         ParamListInfo portalParams; /* params to pass to query */
 110
 111         /* Features/options */
 112         PortalStrategy strategy;        /* see above */
 113         int                     cursorOptions;  /* DECLARE CURSOR option bits */
 114
 115         /* Status data */
 116         bool            portalReady;    /* PortalStart complete? */
 117         bool            portalUtilReady;        /* PortalRunUtility complete? */
 118         bool            portalActive;   /* portal is running (can't delete it) */
 119         bool            portalDone;             /* portal is finished (don't re-run it) */
 120
 121         /* If not NULL, Executor is active; call ExecutorEnd eventually: */
 122         QueryDesc  *queryDesc;          /* info needed for executor invocation */
 123
 124         /* If portal returns tuples, this is their tupdesc: */
 125         TupleDesc       tupDesc;                /* descriptor for result tuples */
 126         /* and these are the format codes to use for the columns: */
 127         int16      *formats;            /* a format code for each column */
 128
 129         /*
 130          * Where we store tuples for a held cursor or a PORTAL_UTIL_SELECT
 131          * query. (A cursor held past the end of its transaction no longer has
 132          * any active executor state.)
 133          */
 134         Tuplestorestate *holdStore; /* store for holdable cursors */
 135         MemoryContext holdContext;      /* memory containing holdStore */
 136
 137         /*
 138          * atStart, atEnd and portalPos indicate the current cursor position.
 139          * portalPos is zero before the first row, N after fetching N'th row
 140          * of query.  After we run off the end, portalPos = # of rows in
 141          * query, and atEnd is true.  If portalPos overflows, set posOverflow
 142          * (this causes us to stop relying on its value for navigation).  Note
 143          * that atStart implies portalPos == 0, but not the reverse (portalPos
 144          * could have overflowed).
 145          */
 146         bool            atStart;
 147         bool            atEnd;
 148         bool            posOverflow;
 149         long            portalPos;
 150 } PortalData;
 151
 152 /*
 153  * PortalIsValid
 154  *              True iff portal is valid.
 155  */
 156 #define PortalIsValid(p) PointerIsValid(p)
 157
 158 /*
 159  * Access macros for Portal ... use these in preference to field access.
 160  */
 161 #define PortalGetQueryDesc(portal)      ((portal)->queryDesc)
 162 #define PortalGetHeapMemory(portal) ((portal)->heap)
 163
 164
 165 /* Prototypes for functions in utils/mmgr/portalmem.c */
 166 extern void EnablePortalManager(void);
 167 extern void AtCommit_Portals(void);
 168 extern void AtAbort_Portals(void);
 169 extern void AtCleanup_Portals(void);
 170 extern Portal CreatePortal(const char *name, bool allowDup, bool dupSilent);
 171 extern Portal CreateNewPortal(void);
 172 extern void PortalDrop(Portal portal, bool isError);
 173 extern void DropDependentPortals(MemoryContext queryContext);
 174 extern Portal GetPortalByName(const char *name);
 175 extern void PortalDefineQuery(Portal portal,
 176                                   const char *sourceText,
 177                                   const char *commandTag,
 178                                   List *parseTrees,
 179                                   List *planTrees,
 180                                   MemoryContext queryContext);
 181 extern void PortalCreateHoldStore(Portal portal);
 182
 183 #endif   /* PORTAL_H */