Eneboo - Documentación para desarrolladores
src/libpq/include/utils/portal.h
Ir a la documentación de este archivo.
00001 /*-------------------------------------------------------------------------
00002  *
00003  * portal.h
00004  *        POSTGRES portal definitions.
00005  *
00006  * A portal is an abstraction which represents the execution state of
00007  * a running or runnable query.  Portals support both SQL-level CURSORs
00008  * and protocol-level portals.
00009  *
00010  * Scrolling (nonsequential access) and suspension of execution are allowed
00011  * only for portals that contain a single SELECT-type query.  We do not want
00012  * to let the client suspend an update-type query partway through!      Because
00013  * the query rewriter does not allow arbitrary ON SELECT rewrite rules,
00014  * only queries that were originally update-type could produce multiple
00015  * parse/plan trees; so the restriction to a single query is not a problem
00016  * in practice.
00017  *
00018  * For SQL cursors, we support three kinds of scroll behavior:
00019  *
00020  * (1) Neither NO SCROLL nor SCROLL was specified: to remain backward
00021  *         compatible, we allow backward fetches here, unless it would
00022  *         impose additional runtime overhead to do so.
00023  *
00024  * (2) NO SCROLL was specified: don't allow any backward fetches.
00025  *
00026  * (3) SCROLL was specified: allow all kinds of backward fetches, even
00027  *         if we need to take a performance hit to do so.  (The planner sticks
00028  *         a Materialize node atop the query plan if needed.)
00029  *
00030  * Case #1 is converted to #2 or #3 by looking at the query itself and
00031  * determining if scrollability can be supported without additional
00032  * overhead.
00033  *
00034  * Protocol-level portals have no nonsequential-fetch API and so the
00035  * distinction doesn't matter for them.  They are always initialized
00036  * to look like NO SCROLL cursors.
00037  *
00038  *
00039  * Portions Copyright (c) 1996-2005, PostgreSQL Global Development Group
00040  * Portions Copyright (c) 1994, Regents of the University of California
00041  *
00042  * $PostgreSQL: pgsql/src/include/utils/portal.h,v 1.57 2005/10/15 02:49:46 momjian Exp $
00043  *
00044  *-------------------------------------------------------------------------
00045  */
00046 #ifndef PORTAL_H
00047 #define PORTAL_H
00048 
00049 #include "executor/execdesc.h"
00050 #include "nodes/memnodes.h"
00051 #include "utils/resowner.h"
00052 #include "utils/tuplestore.h"
00053 
00054 
00055 /*
00056  * We have several execution strategies for Portals, depending on what
00057  * query or queries are to be executed.  (Note: in all cases, a Portal
00058  * executes just a single source-SQL query, and thus produces just a
00059  * single result from the user's viewpoint.  However, the rule rewriter
00060  * may expand the single source query to zero or many actual queries.)
00061  *
00062  * PORTAL_ONE_SELECT: the portal contains one single SELECT query.      We run
00063  * the Executor incrementally as results are demanded.  This strategy also
00064  * supports holdable cursors (the Executor results can be dumped into a
00065  * tuplestore for access after transaction completion).
00066  *
00067  * PORTAL_UTIL_SELECT: the portal contains a utility statement that returns
00068  * a SELECT-like result (for example, EXPLAIN or SHOW).  On first execution,
00069  * we run the statement and dump its results into the portal tuplestore;
00070  * the results are then returned to the client as demanded.
00071  *
00072  * PORTAL_MULTI_QUERY: all other cases.  Here, we do not support partial
00073  * execution: the portal's queries will be run to completion on first call.
00074  */
00075 
00076 typedef enum PortalStrategy
00077 {
00078         PORTAL_ONE_SELECT,
00079         PORTAL_UTIL_SELECT,
00080         PORTAL_MULTI_QUERY
00081 } PortalStrategy;
00082 
00083 /*
00084  * A portal is always in one of these states.  It is possible to transit
00085  * from ACTIVE back to READY if the query is not run to completion;
00086  * otherwise we never back up in status.
00087  */
00088 typedef enum PortalStatus
00089 {
00090         PORTAL_NEW,                                     /* in process of creation */
00091         PORTAL_READY,                           /* PortalStart complete, can run it */
00092         PORTAL_ACTIVE,                          /* portal is running (can't delete it) */
00093         PORTAL_DONE,                            /* portal is finished (don't re-run it) */
00094         PORTAL_FAILED                           /* portal got error (can't re-run it) */
00095 } PortalStatus;
00096 
00097 /*
00098  * Note: typedef Portal is declared in tcop/dest.h as
00099  *              typedef struct PortalData *Portal;
00100  */
00101 
00102 typedef struct PortalData
00103 {
00104         /* Bookkeeping data */
00105         const char *name;                       /* portal's name */
00106         MemoryContext heap;                     /* subsidiary memory for portal */
00107         ResourceOwner resowner;         /* resources owned by portal */
00108         void            (*cleanup) (Portal portal);             /* cleanup hook */
00109         SubTransactionId createSubid;           /* the ID of the creating subxact */
00110 
00111         /*
00112          * if createSubid is InvalidSubTransactionId, the portal is held over from
00113          * a previous transaction
00114          */
00115 
00116         /* The query or queries the portal will execute */
00117         const char *sourceText;         /* text of query, if known (may be NULL) */
00118         const char *commandTag;         /* command tag for original query */
00119         List       *parseTrees;         /* parse tree(s) */
00120         List       *planTrees;          /* plan tree(s) */
00121         MemoryContext queryContext; /* where the above trees live */
00122 
00123         /*
00124          * Note: queryContext effectively identifies which prepared statement the
00125          * portal depends on, if any.  The queryContext is *not* owned by the
00126          * portal and is not to be deleted by portal destruction.  (But for a
00127          * cursor it is the same as "heap", and that context is deleted by portal
00128          * destruction.)
00129          */
00130         ParamListInfo portalParams; /* params to pass to query */
00131 
00132         /* Features/options */
00133         PortalStrategy strategy;        /* see above */
00134         int                     cursorOptions;  /* DECLARE CURSOR option bits */
00135 
00136         /* Status data */
00137         PortalStatus status;            /* see above */
00138         bool            portalUtilReady;        /* PortalRunUtility complete? */
00139 
00140         /* If not NULL, Executor is active; call ExecutorEnd eventually: */
00141         QueryDesc  *queryDesc;          /* info needed for executor invocation */
00142 
00143         /* If portal returns tuples, this is their tupdesc: */
00144         TupleDesc       tupDesc;                /* descriptor for result tuples */
00145         /* and these are the format codes to use for the columns: */
00146         int16      *formats;            /* a format code for each column */
00147 
00148         /*
00149          * Where we store tuples for a held cursor or a PORTAL_UTIL_SELECT query.
00150          * (A cursor held past the end of its transaction no longer has any active
00151          * executor state.)
00152          */
00153         Tuplestorestate *holdStore; /* store for holdable cursors */
00154         MemoryContext holdContext;      /* memory containing holdStore */
00155 
00156         /*
00157          * atStart, atEnd and portalPos indicate the current cursor position.
00158          * portalPos is zero before the first row, N after fetching N'th row of
00159          * query.  After we run off the end, portalPos = # of rows in query, and
00160          * atEnd is true.  If portalPos overflows, set posOverflow (this causes us
00161          * to stop relying on its value for navigation).  Note that atStart
00162          * implies portalPos == 0, but not the reverse (portalPos could have
00163          * overflowed).
00164          */
00165         bool            atStart;
00166         bool            atEnd;
00167         bool            posOverflow;
00168         long            portalPos;
00169 } PortalData;
00170 
00171 /*
00172  * PortalIsValid
00173  *              True iff portal is valid.
00174  */
00175 #define PortalIsValid(p) PointerIsValid(p)
00176 
00177 /*
00178  * Access macros for Portal ... use these in preference to field access.
00179  */
00180 #define PortalGetQueryDesc(portal)      ((portal)->queryDesc)
00181 #define PortalGetHeapMemory(portal) ((portal)->heap)
00182 
00183 
00184 /* Prototypes for functions in utils/mmgr/portalmem.c */
00185 extern void EnablePortalManager(void);
00186 extern bool CommitHoldablePortals(void);
00187 extern bool PrepareHoldablePortals(void);
00188 extern void AtCommit_Portals(void);
00189 extern void AtAbort_Portals(void);
00190 extern void AtCleanup_Portals(void);
00191 extern void AtSubCommit_Portals(SubTransactionId mySubid,
00192                                         SubTransactionId parentSubid,
00193                                         ResourceOwner parentXactOwner);
00194 extern void AtSubAbort_Portals(SubTransactionId mySubid,
00195                                    SubTransactionId parentSubid,
00196                                    ResourceOwner parentXactOwner);
00197 extern void AtSubCleanup_Portals(SubTransactionId mySubid);
00198 extern Portal CreatePortal(const char *name, bool allowDup, bool dupSilent);
00199 extern Portal CreateNewPortal(void);
00200 extern void PortalDrop(Portal portal, bool isTopCommit);
00201 extern void DropDependentPortals(MemoryContext queryContext);
00202 extern Portal GetPortalByName(const char *name);
00203 extern void PortalDefineQuery(Portal portal,
00204                                   const char *sourceText,
00205                                   const char *commandTag,
00206                                   List *parseTrees,
00207                                   List *planTrees,
00208                                   MemoryContext queryContext);
00209 extern void PortalCreateHoldStore(Portal portal);
00210 
00211 #endif   /* PORTAL_H */
 Todo Clases Namespaces Archivos Funciones Variables 'typedefs' Enumeraciones Valores de enumeraciones Propiedades Amigas 'defines'