portal.h File Reference

#include "datatype/timestamp.h"
#include "executor/execdesc.h"
#include "tcop/cmdtag.h"
#include "utils/plancache.h"
#include "utils/resowner.h"

Include dependency graph for portal.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	PortalData

Macros
#define	PortalIsValid(p)   ((p) != NULL)

Typedefs
typedef enum PortalStrategy	PortalStrategy
typedef enum PortalStatus	PortalStatus
typedef struct PortalData *	Portal
typedef struct PortalData	PortalData

Enumerations
enum	PortalStrategy {   PORTAL_ONE_SELECT , PORTAL_ONE_RETURNING , PORTAL_ONE_MOD_WITH , PORTAL_UTIL_SELECT ,   PORTAL_MULTI_QUERY }
enum	PortalStatus {   PORTAL_NEW , PORTAL_DEFINED , PORTAL_READY , PORTAL_ACTIVE ,   PORTAL_DONE , PORTAL_FAILED }

Functions
void	EnablePortalManager (void)
bool	PreCommit_Portals (bool isPrepare)
void	AtAbort_Portals (void)
void	AtCleanup_Portals (void)
void	PortalErrorCleanup (void)
void	AtSubCommit_Portals (SubTransactionId mySubid, SubTransactionId parentSubid, int parentLevel, ResourceOwner parentXactOwner)
void	AtSubAbort_Portals (SubTransactionId mySubid, SubTransactionId parentSubid, ResourceOwner myXactOwner, ResourceOwner parentXactOwner)
void	AtSubCleanup_Portals (SubTransactionId mySubid)
Portal	CreatePortal (const char *name, bool allowDup, bool dupSilent)
Portal	CreateNewPortal (void)
void	PinPortal (Portal portal)
void	UnpinPortal (Portal portal)
void	MarkPortalActive (Portal portal)
void	MarkPortalDone (Portal portal)
void	MarkPortalFailed (Portal portal)
void	PortalDrop (Portal portal, bool isTopCommit)
Portal	GetPortalByName (const char *name)
void	PortalDefineQuery (Portal portal, const char *prepStmtName, const char *sourceText, CommandTag commandTag, List *stmts, CachedPlan *cplan)
PlannedStmt *	PortalGetPrimaryStmt (Portal portal)
void	PortalCreateHoldStore (Portal portal)
void	PortalHashTableDeleteAll (void)
bool	ThereAreNoReadyPortals (void)
void	HoldPinnedPortals (void)
void	ForgetPortalSnapshots (void)

Macro Definition Documentation

PortalIsValid

#define PortalIsValid

(

p

)

((p) != NULL)

Definition at line 211 of file portal.h.

Typedef Documentation

Portal

typedef struct PortalData* Portal

Definition at line 113 of file portal.h.

PortalData

typedef struct PortalData PortalData

PortalStatus

typedef enum PortalStatus PortalStatus

PortalStrategy

typedef enum PortalStrategy PortalStrategy

Enumeration Type Documentation

PortalStatus

enum PortalStatus

Enumerator
PORTAL_NEW
PORTAL_DEFINED
PORTAL_READY
PORTAL_ACTIVE
PORTAL_DONE
PORTAL_FAILED

Definition at line 103 of file portal.h.

{
    PORTAL_NEW,                 /* freshly created */
    PORTAL_DEFINED,             /* PortalDefineQuery done */
    PORTAL_READY,               /* PortalStart complete, can run it */
    PORTAL_ACTIVE,              /* portal is running (can't delete it) */
    PORTAL_DONE,                /* portal is finished (don't re-run it) */
    PORTAL_FAILED,              /* portal got error (can't re-run it) */
} PortalStatus;

PortalStrategy

enum PortalStrategy

Enumerator
PORTAL_ONE_SELECT
PORTAL_ONE_RETURNING
PORTAL_ONE_MOD_WITH
PORTAL_UTIL_SELECT
PORTAL_MULTI_QUERY

Definition at line 89 of file portal.h.

{
    PORTAL_ONE_SELECT,
    PORTAL_ONE_RETURNING,
    PORTAL_ONE_MOD_WITH,
    PORTAL_UTIL_SELECT,
    PORTAL_MULTI_QUERY,
} PortalStrategy;

Function Documentation

AtAbort_Portals()

void AtAbort_Portals ( void  )

extern

Definition at line 782 of file portalmem.c.

{
    HASH_SEQ_STATUS status;
    PortalHashEnt *hentry;
 
    hash_seq_init(&status, PortalHashTable);
 
    while ((hentry = (PortalHashEnt *) hash_seq_search(&status)) != NULL)
    {
        Portal      portal = hentry->portal;
 
        /*
         * When elog(FATAL) is progress, we need to set the active portal to
         * failed, so that PortalCleanup() doesn't run the executor shutdown.
         */
        if (portal->status == PORTAL_ACTIVE && shmem_exit_inprogress)
            MarkPortalFailed(portal);
 
        /*
         * Do nothing else to cursors held over from a previous transaction.
         */
        if (portal->createSubid == InvalidSubTransactionId)
            continue;
 
        /*
         * Do nothing to auto-held cursors.  This is similar to the case of a
         * cursor from a previous transaction, but it could also be that the
         * cursor was auto-held in this transaction, so it wants to live on.
         */
        if (portal->autoHeld)
            continue;
 
        /*
         * If it was created in the current transaction, we can't do normal
         * shutdown on a READY portal either; it might refer to objects
         * created in the failed transaction.  See comments in
         * AtSubAbort_Portals.
         */
        if (portal->status == PORTAL_READY)
            MarkPortalFailed(portal);
 
        /*
         * Allow portalcmds.c to clean up the state it knows about, if we
         * haven't already.
         */
        if (portal->cleanup)
        {
            portal->cleanup(portal);
            portal->cleanup = NULL;
        }
 
        /* drop cached plan reference, if any */
        PortalReleaseCachedPlan(portal);
 
        /*
         * Any resources belonging to the portal will be released in the
         * upcoming transaction-wide cleanup; they will be gone before we run
         * PortalDrop.
         */
        portal->resowner = NULL;
 
        /*
         * Although we can't delete the portal data structure proper, we can
         * release any memory in subsidiary contexts, such as executor state.
         * The cleanup hook was the last thing that might have needed data
         * there.  But leave active portals alone.
         */
        if (portal->status != PORTAL_ACTIVE)
            MemoryContextDeleteChildren(portal->portalContext);
    }
}

References PortalData::autoHeld, PortalData::cleanup, PortalData::createSubid, fb(), hash_seq_init(), hash_seq_search(), InvalidSubTransactionId, MarkPortalFailed(), MemoryContextDeleteChildren(), PORTAL_ACTIVE, PORTAL_READY, PortalData::portalContext, PortalHashTable, PortalReleaseCachedPlan(), PortalData::resowner, shmem_exit_inprogress, and PortalData::status.

Referenced by AbortOutOfAnyTransaction(), and AbortTransaction().

AtCleanup_Portals()

void AtCleanup_Portals ( void  )

extern

Definition at line 860 of file portalmem.c.

{
    HASH_SEQ_STATUS status;
    PortalHashEnt *hentry;
 
    hash_seq_init(&status, PortalHashTable);
 
    while ((hentry = (PortalHashEnt *) hash_seq_search(&status)) != NULL)
    {
        Portal      portal = hentry->portal;
 
        /*
         * Do not touch active portals --- this can only happen in the case of
         * a multi-transaction command.
         */
        if (portal->status == PORTAL_ACTIVE)
            continue;
 
        /*
         * Do nothing to cursors held over from a previous transaction or
         * auto-held ones.
         */
        if (portal->createSubid == InvalidSubTransactionId || portal->autoHeld)
        {
            Assert(portal->status != PORTAL_ACTIVE);
            Assert(portal->resowner == NULL);
            continue;
        }
 
        /*
         * If a portal is still pinned, forcibly unpin it. PortalDrop will not
         * let us drop the portal otherwise. Whoever pinned the portal was
         * interrupted by the abort too and won't try to use it anymore.
         */
        if (portal->portalPinned)
            portal->portalPinned = false;
 
        /*
         * We had better not call any user-defined code during cleanup, so if
         * the cleanup hook hasn't been run yet, too bad; we'll just skip it.
         */
        if (portal->cleanup)
        {
            elog(WARNING, "skipping cleanup for portal \"%s\"", portal->name);
            portal->cleanup = NULL;
        }
 
        /* Zap it. */
        PortalDrop(portal, false);
    }
}

References Assert, PortalData::autoHeld, PortalData::cleanup, PortalData::createSubid, elog, fb(), hash_seq_init(), hash_seq_search(), InvalidSubTransactionId, PortalData::name, PORTAL_ACTIVE, PortalDrop(), PortalHashTable, PortalData::portalPinned, PortalData::resowner, PortalData::status, and WARNING.

Referenced by CleanupTransaction().

AtSubAbort_Portals()

void AtSubAbort_Portals ( SubTransactionId  mySubid, SubTransactionId  parentSubid, ResourceOwner  myXactOwner, ResourceOwner  parentXactOwner  )

extern

Definition at line 981 of file portalmem.c.

{
    HASH_SEQ_STATUS status;
    PortalHashEnt *hentry;
 
    hash_seq_init(&status, PortalHashTable);
 
    while ((hentry = (PortalHashEnt *) hash_seq_search(&status)) != NULL)
    {
        Portal      portal = hentry->portal;
 
        /* Was it created in this subtransaction? */
        if (portal->createSubid != mySubid)
        {
            /* No, but maybe it was used in this subtransaction? */
            if (portal->activeSubid == mySubid)
            {
                /* Maintain activeSubid until the portal is removed */
                portal->activeSubid = parentSubid;
 
                /*
                 * A MarkPortalActive() caller ran an upper-level portal in
                 * this subtransaction and left the portal ACTIVE.  This can't
                 * happen, but force the portal into FAILED state for the same
                 * reasons discussed below.
                 *
                 * We assume we can get away without forcing upper-level READY
                 * portals to fail, even if they were run and then suspended.
                 * In theory a suspended upper-level portal could have
                 * acquired some references to objects that are about to be
                 * destroyed, but there should be sufficient defenses against
                 * such cases: the portal's original query cannot contain such
                 * references, and any references within, say, cached plans of
                 * PL/pgSQL functions are not from active queries and should
                 * be protected by revalidation logic.
                 */
                if (portal->status == PORTAL_ACTIVE)
                    MarkPortalFailed(portal);
 
                /*
                 * Also, if we failed it during the current subtransaction
                 * (either just above, or earlier), reattach its resource
                 * owner to the current subtransaction's resource owner, so
                 * that any resources it still holds will be released while
                 * cleaning up this subtransaction.  This prevents some corner
                 * cases wherein we might get Asserts or worse while cleaning
                 * up objects created during the current subtransaction
                 * (because they're still referenced within this portal).
                 */
                if (portal->status == PORTAL_FAILED && portal->resowner)
                {
                    ResourceOwnerNewParent(portal->resowner, myXactOwner);
                    portal->resowner = NULL;
                }
            }
            /* Done if it wasn't created in this subtransaction */
            continue;
        }
 
        /*
         * Force any live portals of my own subtransaction into FAILED state.
         * We have to do this because they might refer to objects created or
         * changed in the failed subtransaction, leading to crashes within
         * ExecutorEnd when portalcmds.c tries to close down the portal.
         * Currently, every MarkPortalActive() caller ensures it updates the
         * portal status again before relinquishing control, so ACTIVE can't
         * happen here.  If it does happen, dispose the portal like existing
         * MarkPortalActive() callers would.
         */
        if (portal->status == PORTAL_READY ||
            portal->status == PORTAL_ACTIVE)
            MarkPortalFailed(portal);
 
        /*
         * Allow portalcmds.c to clean up the state it knows about, if we
         * haven't already.
         */
        if (portal->cleanup)
        {
            portal->cleanup(portal);
            portal->cleanup = NULL;
        }
 
        /* drop cached plan reference, if any */
        PortalReleaseCachedPlan(portal);
 
        /*
         * Any resources belonging to the portal will be released in the
         * upcoming transaction-wide cleanup; they will be gone before we run
         * PortalDrop.
         */
        portal->resowner = NULL;
 
        /*
         * Although we can't delete the portal data structure proper, we can
         * release any memory in subsidiary contexts, such as executor state.
         * The cleanup hook was the last thing that might have needed data
         * there.
         */
        MemoryContextDeleteChildren(portal->portalContext);
    }
}

References PortalData::activeSubid, PortalData::cleanup, PortalData::createSubid, fb(), hash_seq_init(), hash_seq_search(), MarkPortalFailed(), MemoryContextDeleteChildren(), PORTAL_ACTIVE, PORTAL_FAILED, PORTAL_READY, PortalData::portalContext, PortalHashTable, PortalReleaseCachedPlan(), ResourceOwnerNewParent(), PortalData::resowner, and PortalData::status.

Referenced by AbortOutOfAnyTransaction(), and AbortSubTransaction().

AtSubCleanup_Portals()

void AtSubCleanup_Portals ( SubTransactionId  mySubid )

extern

Definition at line 1094 of file portalmem.c.

{
    HASH_SEQ_STATUS status;
    PortalHashEnt *hentry;
 
    hash_seq_init(&status, PortalHashTable);
 
    while ((hentry = (PortalHashEnt *) hash_seq_search(&status)) != NULL)
    {
        Portal      portal = hentry->portal;
 
        if (portal->createSubid != mySubid)
            continue;
 
        /*
         * If a portal is still pinned, forcibly unpin it. PortalDrop will not
         * let us drop the portal otherwise. Whoever pinned the portal was
         * interrupted by the abort too and won't try to use it anymore.
         */
        if (portal->portalPinned)
            portal->portalPinned = false;
 
        /*
         * We had better not call any user-defined code during cleanup, so if
         * the cleanup hook hasn't been run yet, too bad; we'll just skip it.
         */
        if (portal->cleanup)
        {
            elog(WARNING, "skipping cleanup for portal \"%s\"", portal->name);
            portal->cleanup = NULL;
        }
 
        /* Zap it. */
        PortalDrop(portal, false);
    }
}

References PortalData::cleanup, PortalData::createSubid, elog, fb(), hash_seq_init(), hash_seq_search(), PortalData::name, PortalDrop(), PortalHashTable, PortalData::portalPinned, and WARNING.

Referenced by CleanupSubTransaction().

AtSubCommit_Portals()

void AtSubCommit_Portals ( SubTransactionId  mySubid, SubTransactionId  parentSubid, int  parentLevel, ResourceOwner  parentXactOwner  )

extern

Definition at line 945 of file portalmem.c.

{
    HASH_SEQ_STATUS status;
    PortalHashEnt *hentry;
 
    hash_seq_init(&status, PortalHashTable);
 
    while ((hentry = (PortalHashEnt *) hash_seq_search(&status)) != NULL)
    {
        Portal      portal = hentry->portal;
 
        if (portal->createSubid == mySubid)
        {
            portal->createSubid = parentSubid;
            portal->createLevel = parentLevel;
            if (portal->resowner)
                ResourceOwnerNewParent(portal->resowner, parentXactOwner);
        }
        if (portal->activeSubid == mySubid)
            portal->activeSubid = parentSubid;
    }
}

References PortalData::activeSubid, PortalData::createLevel, PortalData::createSubid, fb(), hash_seq_init(), hash_seq_search(), PortalHashTable, ResourceOwnerNewParent(), and PortalData::resowner.

Referenced by CommitSubTransaction().

CreateNewPortal()

Portal CreateNewPortal ( void  )

extern

Definition at line 237 of file portalmem.c.

{
    static unsigned int unnamed_portal_count = 0;
 
    char        portalname[MAX_PORTALNAME_LEN];
 
    /* Select a nonconflicting name */
    for (;;)
    {
        unnamed_portal_count++;
        sprintf(portalname, "<unnamed portal %u>", unnamed_portal_count);
        if (GetPortalByName(portalname) == NULL)
            break;
    }
 
    return CreatePortal(portalname, false, false);
}

References CreatePortal(), fb(), GetPortalByName(), MAX_PORTALNAME_LEN, and sprintf.

Referenced by ExecuteQuery(), and SPI_cursor_open_internal().

CreatePortal()

Portal CreatePortal ( const char *  name, bool  allowDup, bool  dupSilent  )

extern

Definition at line 177 of file portalmem.c.

{
    Portal      portal;
 
    Assert(name);
 
    portal = GetPortalByName(name);
    if (PortalIsValid(portal))
    {
        if (!allowDup)
            ereport(ERROR,
                    (errcode(ERRCODE_DUPLICATE_CURSOR),
                     errmsg("cursor \"%s\" already exists", name)));
        if (!dupSilent)
            ereport(WARNING,
                    (errcode(ERRCODE_DUPLICATE_CURSOR),
                     errmsg("closing existing cursor \"%s\"",
                            name)));
        PortalDrop(portal, false);
    }
 
    /* make new portal structure */
    portal = (Portal) MemoryContextAllocZero(TopPortalContext, sizeof *portal);
 
    /* initialize portal context; typically it won't store much */
    portal->portalContext = AllocSetContextCreate(TopPortalContext,
                                                  "PortalContext",
                                                  ALLOCSET_SMALL_SIZES);
 
    /* create a resource owner for the portal */
    portal->resowner = ResourceOwnerCreate(CurTransactionResourceOwner,
                                           "Portal");
 
    /* initialize portal fields that don't start off zero */
    portal->status = PORTAL_NEW;
    portal->cleanup = PortalCleanup;
    portal->createSubid = GetCurrentSubTransactionId();
    portal->activeSubid = portal->createSubid;
    portal->createLevel = GetCurrentTransactionNestLevel();
    portal->strategy = PORTAL_MULTI_QUERY;
    portal->cursorOptions = CURSOR_OPT_NO_SCROLL;
    portal->atStart = true;
    portal->atEnd = true;       /* disallow fetches until query is set */
    portal->visible = true;
    portal->creation_time = GetCurrentStatementStartTimestamp();
 
    /* put portal in table (sets portal->name) */
    PortalHashTableInsert(portal, name);
 
    /* for named portals reuse portal->name copy */
    MemoryContextSetIdentifier(portal->portalContext, portal->name[0] ? portal->name : "<unnamed>");
 
    return portal;
}

References PortalData::activeSubid, ALLOCSET_SMALL_SIZES, AllocSetContextCreate, Assert, PortalData::atEnd, PortalData::atStart, PortalData::cleanup, PortalData::createLevel, PortalData::createSubid, PortalData::creation_time, CURSOR_OPT_NO_SCROLL, PortalData::cursorOptions, CurTransactionResourceOwner, ereport, errcode(), errmsg, ERROR, fb(), GetCurrentStatementStartTimestamp(), GetCurrentSubTransactionId(), GetCurrentTransactionNestLevel(), GetPortalByName(), MemoryContextAllocZero(), MemoryContextSetIdentifier(), name, PortalData::name, PORTAL_MULTI_QUERY, PORTAL_NEW, PortalCleanup(), PortalData::portalContext, PortalDrop(), PortalHashTableInsert, PortalIsValid, ResourceOwnerCreate(), PortalData::resowner, PortalData::status, PortalData::strategy, TopPortalContext, PortalData::visible, and WARNING.

Referenced by CreateNewPortal(), exec_bind_message(), exec_simple_query(), PerformCursorOpen(), and SPI_cursor_open_internal().

EnablePortalManager()

void EnablePortalManager ( void  )

extern

Definition at line 106 of file portalmem.c.

{
    HASHCTL     ctl;
 
    Assert(TopPortalContext == NULL);
 
    TopPortalContext = AllocSetContextCreate(TopMemoryContext,
                                             "TopPortalContext",
                                             ALLOCSET_DEFAULT_SIZES);
 
    ctl.keysize = MAX_PORTALNAME_LEN;
    ctl.entrysize = sizeof(PortalHashEnt);
 
    /*
     * use PORTALS_PER_USER as a guess of how many hash table entries to
     * create, initially
     */
    PortalHashTable = hash_create("Portal hash", PORTALS_PER_USER,
                                  &ctl, HASH_ELEM | HASH_STRINGS);
}

References ALLOCSET_DEFAULT_SIZES, AllocSetContextCreate, Assert, ctl, fb(), hash_create(), HASH_ELEM, HASH_STRINGS, MAX_PORTALNAME_LEN, PortalHashTable, PORTALS_PER_USER, TopMemoryContext, and TopPortalContext.

Referenced by InitPostgres().

ForgetPortalSnapshots()

void ForgetPortalSnapshots ( void  )

extern

Definition at line 1258 of file portalmem.c.

{
    HASH_SEQ_STATUS status;
    PortalHashEnt *hentry;
    int         numPortalSnaps = 0;
    int         numActiveSnaps = 0;
 
    /* First, scan PortalHashTable and clear portalSnapshot fields */
    hash_seq_init(&status, PortalHashTable);
 
    while ((hentry = (PortalHashEnt *) hash_seq_search(&status)) != NULL)
    {
        Portal      portal = hentry->portal;
 
        if (portal->portalSnapshot != NULL)
        {
            portal->portalSnapshot = NULL;
            numPortalSnaps++;
        }
        /* portal->holdSnapshot will be cleaned up in PreCommit_Portals */
    }
 
    /*
     * Now, pop all the active snapshots, which should be just those that were
     * portal snapshots.  Ideally we'd drive this directly off the portal
     * scan, but there's no good way to visit the portals in the correct
     * order.  So just cross-check after the fact.
     */
    while (ActiveSnapshotSet())
    {
        PopActiveSnapshot();
        numActiveSnaps++;
    }
 
    if (numPortalSnaps != numActiveSnaps)
        elog(ERROR, "portal snapshots (%d) did not account for all active snapshots (%d)",
             numPortalSnaps, numActiveSnaps);
}

References ActiveSnapshotSet(), elog, ERROR, fb(), hash_seq_init(), hash_seq_search(), PopActiveSnapshot(), PortalHashTable, and PortalData::portalSnapshot.

Referenced by _SPI_commit(), and _SPI_rollback().

GetPortalByName()

Portal GetPortalByName ( const char *  name )

extern

Definition at line 132 of file portalmem.c.

{
    Portal      portal;
 
    if (name)
        PortalHashTableLookup(name, portal);
    else
        portal = NULL;
 
    return portal;
}

References fb(), name, and PortalHashTableLookup.

Referenced by CreateNewPortal(), CreatePortal(), exec_describe_portal_message(), exec_execute_message(), exec_simple_query(), execCurrentOf(), FetchStatementTargetList(), PerformPortalClose(), PerformPortalFetch(), PLy_cursor_close(), PLy_cursor_dealloc(), PLy_cursor_fetch(), PLy_cursor_iternext(), PostgresMain(), SPI_cursor_find(), UtilityReturnsTuples(), and UtilityTupleDescriptor().

HoldPinnedPortals()

void HoldPinnedPortals ( void  )

extern

Definition at line 1209 of file portalmem.c.

{
    HASH_SEQ_STATUS status;
    PortalHashEnt *hentry;
 
    hash_seq_init(&status, PortalHashTable);
 
    while ((hentry = (PortalHashEnt *) hash_seq_search(&status)) != NULL)
    {
        Portal      portal = hentry->portal;
 
        if (portal->portalPinned && !portal->autoHeld)
        {
            /*
             * Doing transaction control, especially abort, inside a cursor
             * loop that is not read-only, for example using UPDATE ...
             * RETURNING, has weird semantics issues.  Also, this
             * implementation wouldn't work, because such portals cannot be
             * held.  (The core grammar enforces that only SELECT statements
             * can drive a cursor, but for example PL/pgSQL does not restrict
             * it.)
             */
            if (portal->strategy != PORTAL_ONE_SELECT)
                ereport(ERROR,
                        (errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
                         errmsg("cannot perform transaction commands inside a cursor loop that is not read-only")));
 
            /* Verify it's in a suitable state to be held */
            if (portal->status != PORTAL_READY)
                elog(ERROR, "pinned portal is not ready to be auto-held");
 
            HoldPortal(portal);
            portal->autoHeld = true;
        }
    }
}

References PortalData::autoHeld, elog, ereport, errcode(), errmsg, ERROR, fb(), hash_seq_init(), hash_seq_search(), HoldPortal(), PORTAL_ONE_SELECT, PORTAL_READY, PortalHashTable, PortalData::portalPinned, PortalData::status, and PortalData::strategy.

Referenced by _SPI_commit(), and _SPI_rollback().

MarkPortalActive()

void MarkPortalActive ( Portal  portal )

extern

Definition at line 396 of file portalmem.c.

{
    /* For safety, this is a runtime test not just an Assert */
    if (portal->status != PORTAL_READY)
        ereport(ERROR,
                (errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
                 errmsg("portal \"%s\" cannot be run", portal->name)));
    /* Perform the state transition */
    portal->status = PORTAL_ACTIVE;
    portal->activeSubid = GetCurrentSubTransactionId();
}

References PortalData::activeSubid, ereport, errcode(), errmsg, ERROR, fb(), GetCurrentSubTransactionId(), PortalData::name, PORTAL_ACTIVE, PORTAL_READY, and PortalData::status.

Referenced by PersistHoldablePortal(), PortalRun(), and PortalRunFetch().

MarkPortalDone()

void MarkPortalDone ( Portal  portal )

extern

Definition at line 415 of file portalmem.c.

{
    /* Perform the state transition */
    Assert(portal->status == PORTAL_ACTIVE);
    portal->status = PORTAL_DONE;
 
    /*
     * Allow portalcmds.c to clean up the state it knows about.  We might as
     * well do that now, since the portal can't be executed any more.
     *
     * In some cases involving execution of a ROLLBACK command in an already
     * aborted transaction, this is necessary, or we'd reach AtCleanup_Portals
     * with the cleanup hook still unexecuted.
     */
    if (portal->cleanup)
    {
        portal->cleanup(portal);
        portal->cleanup = NULL;
    }
}

References Assert, PortalData::cleanup, fb(), PORTAL_ACTIVE, PORTAL_DONE, and PortalData::status.

Referenced by PortalRun().

MarkPortalFailed()

void MarkPortalFailed ( Portal  portal )

extern

Definition at line 443 of file portalmem.c.

{
    /* Perform the state transition */
    Assert(portal->status != PORTAL_DONE);
    portal->status = PORTAL_FAILED;
 
    /*
     * Allow portalcmds.c to clean up the state it knows about.  We might as
     * well do that now, since the portal can't be executed any more.
     *
     * In some cases involving cleanup of an already aborted transaction, this
     * is necessary, or we'd reach AtCleanup_Portals with the cleanup hook
     * still unexecuted.
     */
    if (portal->cleanup)
    {
        portal->cleanup(portal);
        portal->cleanup = NULL;
    }
}

References Assert, PortalData::cleanup, fb(), PORTAL_DONE, PORTAL_FAILED, and PortalData::status.

Referenced by AtAbort_Portals(), AtSubAbort_Portals(), PersistHoldablePortal(), PortalRun(), PortalRunFetch(), and PortalStart().

PinPortal()

void PinPortal ( Portal  portal )

extern

Definition at line 372 of file portalmem.c.

{
    if (portal->portalPinned)
        elog(ERROR, "portal already pinned");
 
    portal->portalPinned = true;
}

References elog, ERROR, and PortalData::portalPinned.

Referenced by exec_for_query(), plperl_spi_query(), plperl_spi_query_prepared(), PLy_cursor_plan(), and PLy_cursor_query().

PortalCreateHoldStore()

void PortalCreateHoldStore ( Portal  portal )

extern

Definition at line 332 of file portalmem.c.

{
    MemoryContext oldcxt;
 
    Assert(portal->holdContext == NULL);
    Assert(portal->holdStore == NULL);
    Assert(portal->holdSnapshot == NULL);
 
    /*
     * Create the memory context that is used for storage of the tuple set.
     * Note this is NOT a child of the portal's portalContext.
     */
    portal->holdContext =
        AllocSetContextCreate(TopPortalContext,
                              "PortalHoldContext",
                              ALLOCSET_DEFAULT_SIZES);
 
    /*
     * Create the tuple store, selecting cross-transaction temp files, and
     * enabling random access only if cursor requires scrolling.
     *
     * XXX: Should maintenance_work_mem be used for the portal size?
     */
    oldcxt = MemoryContextSwitchTo(portal->holdContext);
 
    portal->holdStore =
        tuplestore_begin_heap(portal->cursorOptions & CURSOR_OPT_SCROLL,
                              true, work_mem);
 
    MemoryContextSwitchTo(oldcxt);
}

References ALLOCSET_DEFAULT_SIZES, AllocSetContextCreate, Assert, CURSOR_OPT_SCROLL, PortalData::cursorOptions, fb(), PortalData::holdContext, PortalData::holdSnapshot, PortalData::holdStore, MemoryContextSwitchTo(), TopPortalContext, tuplestore_begin_heap(), and work_mem.

Referenced by FillPortalStore(), and HoldPortal().

PortalDefineQuery()

void PortalDefineQuery ( Portal  portal, const char *  prepStmtName, const char *  sourceText, CommandTag  commandTag, List *  stmts, CachedPlan *  cplan  )

extern

Definition at line 284 of file portalmem.c.

{
    Assert(PortalIsValid(portal));
    Assert(portal->status == PORTAL_NEW);
 
    Assert(sourceText != NULL);
    Assert(commandTag != CMDTAG_UNKNOWN || stmts == NIL);
 
    portal->prepStmtName = prepStmtName;
    portal->sourceText = sourceText;
    portal->commandTag = commandTag;
    SetQueryCompletion(&portal->qc, commandTag, 0);
    portal->stmts = stmts;
    portal->cplan = cplan;
    portal->status = PORTAL_DEFINED;
}

References Assert, PortalData::commandTag, PortalData::cplan, fb(), NIL, PORTAL_DEFINED, PORTAL_NEW, PortalIsValid, PortalData::prepStmtName, PortalData::qc, SetQueryCompletion(), PortalData::sourceText, PortalData::status, and PortalData::stmts.

Referenced by exec_bind_message(), exec_simple_query(), ExecuteQuery(), PerformCursorOpen(), and SPI_cursor_open_internal().

PortalDrop()

void PortalDrop ( Portal  portal, bool  isTopCommit  )

extern

Definition at line 469 of file portalmem.c.

{
    Assert(PortalIsValid(portal));
 
    /*
     * Don't allow dropping a pinned portal, it's still needed by whoever
     * pinned it.
     */
    if (portal->portalPinned)
        ereport(ERROR,
                (errcode(ERRCODE_INVALID_CURSOR_STATE),
                 errmsg("cannot drop pinned portal \"%s\"", portal->name)));
 
    /*
     * Not sure if the PORTAL_ACTIVE case can validly happen or not...
     */
    if (portal->status == PORTAL_ACTIVE)
        ereport(ERROR,
                (errcode(ERRCODE_INVALID_CURSOR_STATE),
                 errmsg("cannot drop active portal \"%s\"", portal->name)));
 
    /*
     * Allow portalcmds.c to clean up the state it knows about, in particular
     * shutting down the executor if still active.  This step potentially runs
     * user-defined code so failure has to be expected.  It's the cleanup
     * hook's responsibility to not try to do that more than once, in the case
     * that failure occurs and then we come back to drop the portal again
     * during transaction abort.
     *
     * Note: in most paths of control, this will have been done already in
     * MarkPortalDone or MarkPortalFailed.  We're just making sure.
     */
    if (portal->cleanup)
    {
        portal->cleanup(portal);
        portal->cleanup = NULL;
    }
 
    /* There shouldn't be an active snapshot anymore, except after error */
    Assert(portal->portalSnapshot == NULL || !isTopCommit);
 
    /*
     * Remove portal from hash table.  Because we do this here, we will not
     * come back to try to remove the portal again if there's any error in the
     * subsequent steps.  Better to leak a little memory than to get into an
     * infinite error-recovery loop.
     */
    PortalHashTableDelete(portal);
 
    /* drop cached plan reference, if any */
    PortalReleaseCachedPlan(portal);
 
    /*
     * If portal has a snapshot protecting its data, release that.  This needs
     * a little care since the registration will be attached to the portal's
     * resowner; if the portal failed, we will already have released the
     * resowner (and the snapshot) during transaction abort.
     */
    if (portal->holdSnapshot)
    {
        if (portal->resowner)
            UnregisterSnapshotFromOwner(portal->holdSnapshot,
                                        portal->resowner);
        portal->holdSnapshot = NULL;
    }
 
    /*
     * Release any resources still attached to the portal.  There are several
     * cases being covered here:
     *
     * Top transaction commit (indicated by isTopCommit): normally we should
     * do nothing here and let the regular end-of-transaction resource
     * releasing mechanism handle these resources too.  However, if we have a
     * FAILED portal (eg, a cursor that got an error), we'd better clean up
     * its resources to avoid resource-leakage warning messages.
     *
     * Sub transaction commit: never comes here at all, since we don't kill
     * any portals in AtSubCommit_Portals().
     *
     * Main or sub transaction abort: we will do nothing here because
     * portal->resowner was already set NULL; the resources were already
     * cleaned up in transaction abort.
     *
     * Ordinary portal drop: must release resources.  However, if the portal
     * is not FAILED then we do not release its locks.  The locks become the
     * responsibility of the transaction's ResourceOwner (since it is the
     * parent of the portal's owner) and will be released when the transaction
     * eventually ends.
     */
    if (portal->resowner &&
        (!isTopCommit || portal->status == PORTAL_FAILED))
    {
        bool        isCommit = (portal->status != PORTAL_FAILED);
 
        ResourceOwnerRelease(portal->resowner,
                             RESOURCE_RELEASE_BEFORE_LOCKS,
                             isCommit, false);
        ResourceOwnerRelease(portal->resowner,
                             RESOURCE_RELEASE_LOCKS,
                             isCommit, false);
        ResourceOwnerRelease(portal->resowner,
                             RESOURCE_RELEASE_AFTER_LOCKS,
                             isCommit, false);
        ResourceOwnerDelete(portal->resowner);
    }
    portal->resowner = NULL;
 
    /*
     * Delete tuplestore if present.  We should do this even under error
     * conditions; since the tuplestore would have been using cross-
     * transaction storage, its temp files need to be explicitly deleted.
     */
    if (portal->holdStore)
    {
        MemoryContext oldcontext;
 
        oldcontext = MemoryContextSwitchTo(portal->holdContext);
        tuplestore_end(portal->holdStore);
        MemoryContextSwitchTo(oldcontext);
        portal->holdStore = NULL;
    }
 
    /* delete tuplestore storage, if any */
    if (portal->holdContext)
        MemoryContextDelete(portal->holdContext);
 
    /* release subsidiary storage */
    MemoryContextDelete(portal->portalContext);
 
    /* release portal struct (it's in TopPortalContext) */
    pfree(portal);
}

References Assert, PortalData::cleanup, ereport, errcode(), errmsg, ERROR, fb(), PortalData::holdContext, PortalData::holdSnapshot, PortalData::holdStore, MemoryContextDelete(), MemoryContextSwitchTo(), PortalData::name, pfree(), PORTAL_ACTIVE, PORTAL_FAILED, PortalData::portalContext, PortalHashTableDelete, PortalIsValid, PortalData::portalPinned, PortalReleaseCachedPlan(), PortalData::portalSnapshot, RESOURCE_RELEASE_AFTER_LOCKS, RESOURCE_RELEASE_BEFORE_LOCKS, RESOURCE_RELEASE_LOCKS, ResourceOwnerDelete(), ResourceOwnerRelease(), PortalData::resowner, PortalData::status, tuplestore_end(), and UnregisterSnapshotFromOwner().

Referenced by AtCleanup_Portals(), AtSubCleanup_Portals(), CreatePortal(), exec_simple_query(), ExecuteQuery(), PerformPortalClose(), PortalErrorCleanup(), PortalHashTableDeleteAll(), PostgresMain(), PreCommit_Portals(), and SPI_cursor_close().

PortalErrorCleanup()

void PortalErrorCleanup ( void  )

extern

Definition at line 919 of file portalmem.c.

{
    HASH_SEQ_STATUS status;
    PortalHashEnt *hentry;
 
    hash_seq_init(&status, PortalHashTable);
 
    while ((hentry = (PortalHashEnt *) hash_seq_search(&status)) != NULL)
    {
        Portal      portal = hentry->portal;
 
        if (portal->autoHeld)
        {
            portal->portalPinned = false;
            PortalDrop(portal, false);
        }
    }
}

References PortalData::autoHeld, fb(), hash_seq_init(), hash_seq_search(), PortalDrop(), PortalHashTable, and PortalData::portalPinned.

Referenced by PostgresMain().

PortalGetPrimaryStmt()

PlannedStmt * PortalGetPrimaryStmt ( Portal  portal )

extern

Definition at line 153 of file portalmem.c.

{
    ListCell   *lc;
 
    foreach(lc, portal->stmts)
    {
        PlannedStmt *stmt = lfirst_node(PlannedStmt, lc);
 
        if (stmt->canSetTag)
            return stmt;
    }
    return NULL;
}

References fb(), lfirst_node, stmt, and PortalData::stmts.

Referenced by FetchPortalTargetList(), and PortalStart().

PortalHashTableDeleteAll()

void PortalHashTableDeleteAll ( void  )

extern

Definition at line 608 of file portalmem.c.

{
    HASH_SEQ_STATUS status;
    PortalHashEnt *hentry;
 
    if (PortalHashTable == NULL)
        return;
 
    hash_seq_init(&status, PortalHashTable);
    while ((hentry = hash_seq_search(&status)) != NULL)
    {
        Portal      portal = hentry->portal;
 
        /* Can't close the active portal (the one running the command) */
        if (portal->status == PORTAL_ACTIVE)
            continue;
 
        PortalDrop(portal, false);
 
        /* Restart the iteration in case that led to other drops */
        hash_seq_term(&status);
        hash_seq_init(&status, PortalHashTable);
    }
}

References fb(), hash_seq_init(), hash_seq_search(), hash_seq_term(), PORTAL_ACTIVE, PortalDrop(), PortalHashTable, and PortalData::status.

Referenced by DiscardAll(), and PerformPortalClose().

PreCommit_Portals()

bool PreCommit_Portals ( bool  isPrepare )

extern

Definition at line 678 of file portalmem.c.

{
    bool        result = false;
    HASH_SEQ_STATUS status;
    PortalHashEnt *hentry;
 
    hash_seq_init(&status, PortalHashTable);
 
    while ((hentry = (PortalHashEnt *) hash_seq_search(&status)) != NULL)
    {
        Portal      portal = hentry->portal;
 
        /*
         * There should be no pinned portals anymore. Complain if someone
         * leaked one. Auto-held portals are allowed; we assume that whoever
         * pinned them is managing them.
         */
        if (portal->portalPinned && !portal->autoHeld)
            elog(ERROR, "cannot commit while a portal is pinned");
 
        /*
         * Do not touch active portals --- this can only happen in the case of
         * a multi-transaction utility command, such as VACUUM, or a commit in
         * a procedure.
         *
         * Note however that any resource owner attached to such a portal is
         * still going to go away, so don't leave a dangling pointer.  Also
         * unregister any snapshots held by the portal, mainly to avoid
         * snapshot leak warnings from ResourceOwnerRelease().
         */
        if (portal->status == PORTAL_ACTIVE)
        {
            if (portal->holdSnapshot)
            {
                if (portal->resowner)
                    UnregisterSnapshotFromOwner(portal->holdSnapshot,
                                                portal->resowner);
                portal->holdSnapshot = NULL;
            }
            portal->resowner = NULL;
            /* Clear portalSnapshot too, for cleanliness */
            portal->portalSnapshot = NULL;
            continue;
        }
 
        /* Is it a holdable portal created in the current xact? */
        if ((portal->cursorOptions & CURSOR_OPT_HOLD) &&
            portal->createSubid != InvalidSubTransactionId &&
            portal->status == PORTAL_READY)
        {
            /*
             * We are exiting the transaction that created a holdable cursor.
             * Instead of dropping the portal, prepare it for access by later
             * transactions.
             *
             * However, if this is PREPARE TRANSACTION rather than COMMIT,
             * refuse PREPARE, because the semantics seem pretty unclear.
             */
            if (isPrepare)
                ereport(ERROR,
                        (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
                         errmsg("cannot PREPARE a transaction that has created a cursor WITH HOLD")));
 
            HoldPortal(portal);
 
            /* Report we changed state */
            result = true;
        }
        else if (portal->createSubid == InvalidSubTransactionId)
        {
            /*
             * Do nothing to cursors held over from a previous transaction
             * (including ones we just froze in a previous cycle of this loop)
             */
            continue;
        }
        else
        {
            /* Zap all non-holdable portals */
            PortalDrop(portal, true);
 
            /* Report we changed state */
            result = true;
        }
 
        /*
         * After either freezing or dropping a portal, we have to restart the
         * iteration, because we could have invoked user-defined code that
         * caused a drop of the next portal in the hash chain.
         */
        hash_seq_term(&status);
        hash_seq_init(&status, PortalHashTable);
    }
 
    return result;
}

References PortalData::autoHeld, PortalData::createSubid, CURSOR_OPT_HOLD, PortalData::cursorOptions, elog, ereport, errcode(), errmsg, ERROR, fb(), hash_seq_init(), hash_seq_search(), hash_seq_term(), HoldPortal(), PortalData::holdSnapshot, InvalidSubTransactionId, PORTAL_ACTIVE, PORTAL_READY, PortalDrop(), PortalHashTable, PortalData::portalPinned, PortalData::portalSnapshot, PortalData::resowner, PortalData::status, and UnregisterSnapshotFromOwner().

Referenced by CommitTransaction(), and PrepareTransaction().

ThereAreNoReadyPortals()

bool ThereAreNoReadyPortals ( void  )

extern

Definition at line 1173 of file portalmem.c.

{
    HASH_SEQ_STATUS status;
    PortalHashEnt *hentry;
 
    hash_seq_init(&status, PortalHashTable);
 
    while ((hentry = (PortalHashEnt *) hash_seq_search(&status)) != NULL)
    {
        Portal      portal = hentry->portal;
 
        if (portal->status == PORTAL_READY)
            return false;
    }
 
    return true;
}

References fb(), hash_seq_init(), hash_seq_search(), PORTAL_READY, PortalHashTable, and PortalData::status.

Referenced by CopyFrom().

UnpinPortal()

void UnpinPortal ( Portal  portal )

extern

Definition at line 381 of file portalmem.c.

{
    if (!portal->portalPinned)
        elog(ERROR, "portal not pinned");
 
    portal->portalPinned = false;
}

References elog, ERROR, and PortalData::portalPinned.

Referenced by exec_for_query(), plperl_spi_cursor_close(), plperl_spi_fetchrow(), PLy_cursor_close(), and PLy_cursor_dealloc().