execScan.h

Go to the documentation of this file.

/*-------------------------------------------------------------------------
 * execScan.h
 *      Inline-able support functions for Scan nodes
 *
 * Portions Copyright (c) 1996-2026, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994, Regents of the University of California
 *
 * IDENTIFICATION
 *      src/include/executor/execScan.h
 *-------------------------------------------------------------------------
 */
 
#ifndef EXECSCAN_H
#define EXECSCAN_H
 
#include "miscadmin.h"
#include "executor/executor.h"
#include "executor/instrument.h"
#include "nodes/execnodes.h"
 
/*
 * ExecScanFetch -- check interrupts & fetch next potential tuple
 *
 * This routine substitutes a test tuple if inside an EvalPlanQual recheck.
 * Otherwise, it simply executes the access method's next-tuple routine.
 *
 * The pg_always_inline attribute allows the compiler to inline this function
 * into its caller. When EPQState is NULL, the EvalPlanQual logic is completely
 * eliminated at compile time, avoiding unnecessary run-time checks and code
 * for cases where EPQ is not required.
 */
static pg_always_inline TupleTableSlot *
ExecScanFetch(ScanState *node,
              EPQState *epqstate,
              ExecScanAccessMtd accessMtd,
              ExecScanRecheckMtd recheckMtd)
{
    CHECK_FOR_INTERRUPTS();
 
    if (epqstate != NULL)
    {
        /*
         * We are inside an EvalPlanQual recheck.  Return the test tuple if
         * one is available, after rechecking any access-method-specific
         * conditions.
         */
        Index       scanrelid = ((Scan *) node->ps.plan)->scanrelid;
 
        if (scanrelid == 0)
        {
            /*
             * This is a ForeignScan or CustomScan which has pushed down a
             * join to the remote side.  If it is a descendant node in the EPQ
             * recheck plan tree, run the recheck method function.  Otherwise,
             * run the access method function below.
             */
            if (bms_is_member(epqstate->epqParam, node->ps.plan->extParam))
            {
                /*
                 * The recheck method is responsible not only for rechecking
                 * the scan/join quals but also for storing the correct tuple
                 * in the slot.
                 */
 
                TupleTableSlot *slot = node->ss_ScanTupleSlot;
 
                if (!(*recheckMtd) (node, slot))
                    ExecClearTuple(slot);   /* would not be returned by scan */
                return slot;
            }
        }
        else if (epqstate->relsubs_done[scanrelid - 1])
        {
            /*
             * Return empty slot, as either there is no EPQ tuple for this rel
             * or we already returned it.
             */
 
            TupleTableSlot *slot = node->ss_ScanTupleSlot;
 
            return ExecClearTuple(slot);
        }
        else if (epqstate->relsubs_slot[scanrelid - 1] != NULL)
        {
            /*
             * Return replacement tuple provided by the EPQ caller.
             */
 
            TupleTableSlot *slot = epqstate->relsubs_slot[scanrelid - 1];
 
            Assert(epqstate->relsubs_rowmark[scanrelid - 1] == NULL);
 
            /* Mark to remember that we shouldn't return it again */
            epqstate->relsubs_done[scanrelid - 1] = true;
 
            /* Return empty slot if we haven't got a test tuple */
            if (TupIsNull(slot))
                return NULL;
 
            /* Check if it meets the access-method conditions */
            if (!(*recheckMtd) (node, slot))
                return ExecClearTuple(slot);    /* would not be returned by
                                                 * scan */
            return slot;
        }
        else if (epqstate->relsubs_rowmark[scanrelid - 1] != NULL)
        {
            /*
             * Fetch and return replacement tuple using a non-locking rowmark.
             */
 
            TupleTableSlot *slot = node->ss_ScanTupleSlot;
 
            /* Mark to remember that we shouldn't return more */
            epqstate->relsubs_done[scanrelid - 1] = true;
 
            if (!EvalPlanQualFetchRowMark(epqstate, scanrelid, slot))
                return NULL;
 
            /* Return empty slot if we haven't got a test tuple */
            if (TupIsNull(slot))
                return NULL;
 
            /* Check if it meets the access-method conditions */
            if (!(*recheckMtd) (node, slot))
                return ExecClearTuple(slot);    /* would not be returned by
                                                 * scan */
            return slot;
        }
    }
 
    /*
     * Run the node-type-specific access method function to get the next tuple
     */
    return (*accessMtd) (node);
}
 
/* ----------------------------------------------------------------
 * ExecScanExtended
 *      Scans the relation using the specified 'access method' and returns the
 *      next tuple.  Optionally checks the tuple against 'qual' and applies
 *      'projInfo' if provided.
 *
 * The 'recheck method' validates an arbitrary tuple of the relation against
 * conditions enforced by the access method.
 *
 * This function is an alternative to ExecScan, used when callers may omit
 * 'qual' or 'projInfo'. The pg_always_inline attribute allows the compiler
 * to eliminate non-relevant branches at compile time, avoiding run-time
 * checks in those cases.
 *
 * Conditions:
 *  -- The AMI "cursor" is positioned at the previously returned tuple.
 *
 * Initial States:
 *  -- The relation is opened for scanning, with the "cursor"
 *  positioned before the first qualifying tuple.
 * ----------------------------------------------------------------
 */
static pg_always_inline TupleTableSlot *
ExecScanExtended(ScanState *node,
                 ExecScanAccessMtd accessMtd,   /* function returning a tuple */
                 ExecScanRecheckMtd recheckMtd,
                 EPQState *epqstate,
                 ExprState *qual,
                 ProjectionInfo *projInfo)
{
    ExprContext *econtext = node->ps.ps_ExprContext;
 
    /* interrupt checks are in ExecScanFetch */
 
    /*
     * If we have neither a qual to check nor a projection to do, just skip
     * all the overhead and return the raw scan tuple.
     */
    if (!qual && !projInfo)
    {
        ResetExprContext(econtext);
        return ExecScanFetch(node, epqstate, accessMtd, recheckMtd);
    }
 
    /*
     * Reset per-tuple memory context to free any expression evaluation
     * storage allocated in the previous tuple cycle.
     */
    ResetExprContext(econtext);
 
    /*
     * get a tuple from the access method.  Loop until we obtain a tuple that
     * passes the qualification.
     */
    for (;;)
    {
        TupleTableSlot *slot;
 
        slot = ExecScanFetch(node, epqstate, accessMtd, recheckMtd);
 
        /*
         * if the slot returned by the accessMtd contains NULL, then it means
         * there is nothing more to scan so we just return an empty slot,
         * being careful to use the projection result slot so it has correct
         * tupleDesc.
         */
        if (TupIsNull(slot))
        {
            if (projInfo)
                return ExecClearTuple(projInfo->pi_state.resultslot);
            else
                return slot;
        }
 
        /*
         * place the current tuple into the expr context
         */
        econtext->ecxt_scantuple = slot;
 
        /*
         * check that the current tuple satisfies the qual-clause
         *
         * check for non-null qual here to avoid a function call to ExecQual()
         * when the qual is null ... saves only a few cycles, but they add up
         * ...
         */
        if (qual == NULL || ExecQual(qual, econtext))
        {
            /*
             * Found a satisfactory scan tuple.
             */
            if (projInfo)
            {
                /*
                 * Form a projection tuple, store it in the result tuple slot
                 * and return it.
                 */
                return ExecProject(projInfo);
            }
            else
            {
                /*
                 * Here, we aren't projecting, so just return scan tuple.
                 */
                return slot;
            }
        }
        else
            InstrCountFiltered1(node, 1);
 
        /*
         * Tuple fails qual, so free per-tuple memory and try again.
         */
        ResetExprContext(econtext);
    }
}
 
#endif                          /* EXECSCAN_H */