/*-------------------------------------------------------------------------

 *

 * execAmi.c

 *    miscellaneous executor access method routines

 *

 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group

 * Portions Copyright (c) 1994, Regents of the University of California

 *

 *  src/backend/executor/execAmi.c

 *

 *-------------------------------------------------------------------------

 */

#include "postgres.h"

#include "access/amapi.h"

#include "access/htup_details.h"

#include "catalog/pg_class.h"

#include "executor/executor.h"

#include "executor/nodeAgg.h"

#include "executor/nodeAppend.h"

#include "executor/nodeBitmapAnd.h"

#include "executor/nodeBitmapHeapscan.h"

#include "executor/nodeBitmapIndexscan.h"

#include "executor/nodeBitmapOr.h"

#include "executor/nodeCtescan.h"

#include "executor/nodeCustom.h"

#include "executor/nodeForeignscan.h"

#include "executor/nodeFunctionscan.h"

#include "executor/nodeGather.h"

#include "executor/nodeGatherMerge.h"

#include "executor/nodeGroup.h"

#include "executor/nodeHash.h"

#include "executor/nodeHashjoin.h"

#include "executor/nodeIncrementalSort.h"

#include "executor/nodeIndexonlyscan.h"

#include "executor/nodeIndexscan.h"

#include "executor/nodeLimit.h"

#include "executor/nodeLockRows.h"

#include "executor/nodeMaterial.h"

#include "executor/nodeMemoize.h"

#include "executor/nodeMergeAppend.h"

#include "executor/nodeMergejoin.h"

#include "executor/nodeModifyTable.h"

#include "executor/nodeNamedtuplestorescan.h"

#include "executor/nodeNestloop.h"

#include "executor/nodeProjectSet.h"

#include "executor/nodeRecursiveunion.h"

#include "executor/nodeResult.h"

#include "executor/nodeSamplescan.h"

#include "executor/nodeSeqscan.h"

#include "executor/nodeSetOp.h"

#include "executor/nodeSort.h"

#include "executor/nodeSubplan.h"

#include "executor/nodeSubqueryscan.h"

#include "executor/nodeTableFuncscan.h"

#include "executor/nodeTidrangescan.h"

#include "executor/nodeTidscan.h"

#include "executor/nodeUnique.h"

#include "executor/nodeValuesscan.h"

#include "executor/nodeWindowAgg.h"

#include "executor/nodeWorktablescan.h"

#include "nodes/extensible.h"

#include "nodes/pathnodes.h"

#include "utils/syscache.h"

static bool IndexSupportsBackwardScan(Oid indexid);

/*

 * ExecReScan

 *    Reset a plan node so that its output can be re-scanned.

 *

 * Note that if the plan node has parameters that have changed value,

 * the output might be different from last time.

 */

void

ExecReScan(PlanState *node)

{

  /* If collecting timing stats, update them */

  if (node->instrument)

    InstrEndLoop(node->instrument);

  /*

   * If we have changed parameters, propagate that info.

   *

   * Note: ExecReScanSetParamPlan() can add bits to node->chgParam,

   * corresponding to the output param(s) that the InitPlan will update.

   * Since we make only one pass over the list, that means that an InitPlan

   * can depend on the output param(s) of a sibling InitPlan only if that

   * sibling appears earlier in the list.  This is workable for now given

   * the limited ways in which one InitPlan could depend on another, but

   * eventually we might need to work harder (or else make the planner

   * enlarge the extParam/allParam sets to include the params of depended-on

   * InitPlans).

   */

  if (node->chgParam != NULL)

  {

    ListCell   *l;

    foreach(l, node->initPlan)

    {

      SubPlanState *sstate = (SubPlanState *) lfirst(l);

      PlanState  *splan = sstate->planstate;

      if (splan->plan->extParam != NULL) /* don't care about child

                         * local Params */

        UpdateChangedParamSet(splan, node->chgParam);

      if (splan->chgParam != NULL)

        ExecReScanSetParamPlan(sstate, node);

    }

    foreach(l, node->subPlan)

    {

      SubPlanState *sstate = (SubPlanState *) lfirst(l);

      PlanState  *splan = sstate->planstate;

      if (splan->plan->extParam != NULL)

        UpdateChangedParamSet(splan, node->chgParam);

    }

    /* Well. Now set chgParam for child trees. */

    if (outerPlanState(node) != NULL)

      UpdateChangedParamSet(outerPlanState(node), node->chgParam);

    if (innerPlanState(node) != NULL)

      UpdateChangedParamSet(innerPlanState(node), node->chgParam);

  }

  /* Call expression callbacks */

  if (node->ps_ExprContext)

    ReScanExprContext(node->ps_ExprContext);

  /* And do node-type-specific processing */

  switch (nodeTag(node))

  {

    case T_ResultState:

      ExecReScanResult((ResultState *) node);

      break;

    case T_ProjectSetState:

      ExecReScanProjectSet((ProjectSetState *) node);

      break;

    case T_ModifyTableState:

      ExecReScanModifyTable((ModifyTableState *) node);

      break;

    case T_AppendState:

      ExecReScanAppend((AppendState *) node);

      break;

    case T_MergeAppendState:

      ExecReScanMergeAppend((MergeAppendState *) node);

      break;

    case T_RecursiveUnionState:

      ExecReScanRecursiveUnion((RecursiveUnionState *) node);

      break;

    case T_BitmapAndState:

      ExecReScanBitmapAnd((BitmapAndState *) node);

      break;

    case T_BitmapOrState:

      ExecReScanBitmapOr((BitmapOrState *) node);

      break;

    case T_SeqScanState:

      ExecReScanSeqScan((SeqScanState *) node);

      break;

    case T_SampleScanState:

      ExecReScanSampleScan((SampleScanState *) node);

      break;

    case T_GatherState:

      ExecReScanGather((GatherState *) node);

      break;

    case T_GatherMergeState:

      ExecReScanGatherMerge((GatherMergeState *) node);

      break;

    case T_IndexScanState:

      ExecReScanIndexScan((IndexScanState *) node);

      break;

    case T_IndexOnlyScanState:

      ExecReScanIndexOnlyScan((IndexOnlyScanState *) node);

      break;

    case T_BitmapIndexScanState:

      ExecReScanBitmapIndexScan((BitmapIndexScanState *) node);

      break;

    case T_BitmapHeapScanState:

      ExecReScanBitmapHeapScan((BitmapHeapScanState *) node);

      break;

    case T_TidScanState:

      ExecReScanTidScan((TidScanState *) node);

      break;

    case T_TidRangeScanState:

      ExecReScanTidRangeScan((TidRangeScanState *) node);

      break;

    case T_SubqueryScanState:

      ExecReScanSubqueryScan((SubqueryScanState *) node);

      break;

    case T_FunctionScanState:

      ExecReScanFunctionScan((FunctionScanState *) node);

      break;

    case T_TableFuncScanState:

      ExecReScanTableFuncScan((TableFuncScanState *) node);

      break;

    case T_ValuesScanState:

      ExecReScanValuesScan((ValuesScanState *) node);

      break;

    case T_CteScanState:

      ExecReScanCteScan((CteScanState *) node);

      break;

    case T_NamedTuplestoreScanState:

      ExecReScanNamedTuplestoreScan((NamedTuplestoreScanState *) node);

      break;

    case T_WorkTableScanState:

      ExecReScanWorkTableScan((WorkTableScanState *) node);

      break;

    case T_ForeignScanState:

      ExecReScanForeignScan((ForeignScanState *) node);

      break;

    case T_CustomScanState:

      ExecReScanCustomScan((CustomScanState *) node);

      break;

    case T_NestLoopState:

      ExecReScanNestLoop((NestLoopState *) node);

      break;

    case T_MergeJoinState:

      ExecReScanMergeJoin((MergeJoinState *) node);

      break;

    case T_HashJoinState:

      ExecReScanHashJoin((HashJoinState *) node);

      break;

    case T_MaterialState:

      ExecReScanMaterial((MaterialState *) node);

      break;

    case T_MemoizeState:

      ExecReScanMemoize((MemoizeState *) node);

      break;

    case T_SortState:

      ExecReScanSort((SortState *) node);

      break;

    case T_IncrementalSortState:

      ExecReScanIncrementalSort((IncrementalSortState *) node);

      break;

    case T_GroupState:

      ExecReScanGroup((GroupState *) node);

      break;

    case T_AggState:

      ExecReScanAgg((AggState *) node);

      break;

    case T_WindowAggState:

      ExecReScanWindowAgg((WindowAggState *) node);

      break;

    case T_UniqueState:

      ExecReScanUnique((UniqueState *) node);

      break;

    case T_HashState:

      ExecReScanHash((HashState *) node);

      break;

    case T_SetOpState:

      ExecReScanSetOp((SetOpState *) node);

      break;

    case T_LockRowsState:

      ExecReScanLockRows((LockRowsState *) node);

      break;

    case T_LimitState:

      ExecReScanLimit((LimitState *) node);

      break;

    default:

      elog(ERROR, "unrecognized node type: %d", (int) nodeTag(node));

      break;

  }

  if (node->chgParam != NULL)

  {

    bms_free(node->chgParam);

    node->chgParam = NULL;

  }

}

/*

 * ExecMarkPos

 *

 * Marks the current scan position.

 *

 * NOTE: mark/restore capability is currently needed only for plan nodes

 * that are the immediate inner child of a MergeJoin node.  Since MergeJoin

 * requires sorted input, there is never any need to support mark/restore in

 * node types that cannot produce sorted output.  There are some cases in

 * which a node can pass through sorted data from its child; if we don't

 * implement mark/restore for such a node type, the planner compensates by

 * inserting a Material node above that node.

 */

void

ExecMarkPos(PlanState *node)

{

  switch (nodeTag(node))

  {

    case T_IndexScanState:

      ExecIndexMarkPos((IndexScanState *) node);

      break;

    case T_IndexOnlyScanState:

      ExecIndexOnlyMarkPos((IndexOnlyScanState *) node);

      break;

    case T_CustomScanState:

      ExecCustomMarkPos((CustomScanState *) node);

      break;

    case T_MaterialState:

      ExecMaterialMarkPos((MaterialState *) node);

      break;

    case T_SortState:

      ExecSortMarkPos((SortState *) node);

      break;

    case T_ResultState:

      ExecResultMarkPos((ResultState *) node);

      break;

    default:

      /* don't make hard error unless caller asks to restore... */

      elog(DEBUG2, "unrecognized node type: %d", (int) nodeTag(node));

      break;

  }

}

/*

 * ExecRestrPos

 *

 * restores the scan position previously saved with ExecMarkPos()

 *

 * NOTE: the semantics of this are that the first ExecProcNode following

 * the restore operation will yield the same tuple as the first one following

 * the mark operation.  It is unspecified what happens to the plan node's

 * result TupleTableSlot.  (In most cases the result slot is unchanged by

 * a restore, but the node may choose to clear it or to load it with the

 * restored-to tuple.)  Hence the caller should discard any previously

 * returned TupleTableSlot after doing a restore.

 */

void

ExecRestrPos(PlanState *node)

{

  switch (nodeTag(node))

  {

    case T_IndexScanState:

      ExecIndexRestrPos((IndexScanState *) node);

      break;

    case T_IndexOnlyScanState:

      ExecIndexOnlyRestrPos((IndexOnlyScanState *) node);

      break;

    case T_CustomScanState:

      ExecCustomRestrPos((CustomScanState *) node);

      break;

    case T_MaterialState:

      ExecMaterialRestrPos((MaterialState *) node);

      break;

    case T_SortState:

      ExecSortRestrPos((SortState *) node);

      break;

    case T_ResultState:

      ExecResultRestrPos((ResultState *) node);

      break;

    default:

      elog(ERROR, "unrecognized node type: %d", (int) nodeTag(node));

      break;

  }

}

/*

 * ExecSupportsMarkRestore - does a Path support mark/restore?

 *

 * This is used during planning and so must accept a Path, not a Plan.

 * We keep it here to be adjacent to the routines above, which also must

 * know which plan types support mark/restore.

 */

bool

ExecSupportsMarkRestore(Path *pathnode)

{

  /*

   * For consistency with the routines above, we do not examine the nodeTag

   * but rather the pathtype, which is the Plan node type the Path would

   * produce.

   */

  switch (pathnode->pathtype)

  {

    case T_IndexScan:

    case T_IndexOnlyScan:

      /*

       * Not all index types support mark/restore.

       */

      return castNode(IndexPath, pathnode)->indexinfo->amcanmarkpos;

    case T_Material:

    case T_Sort:

      return true;

    case T_CustomScan:

      if (castNode(CustomPath, pathnode)->flags & CUSTOMPATH_SUPPORT_MARK_RESTORE)

        return true;

      return false;

    case T_Result:

      /*

       * Result supports mark/restore iff it has a child plan that does.

       *

       * We have to be careful here because there is more than one Path

       * type that can produce a Result plan node.

       */

      if (IsA(pathnode, ProjectionPath))

        return ExecSupportsMarkRestore(((ProjectionPath *) pathnode)->subpath);

      else if (IsA(pathnode, MinMaxAggPath))

        return false; /* childless Result */

      else if (IsA(pathnode, GroupResultPath))

        return false; /* childless Result */

      else

      {

        /* Simple RTE_RESULT base relation */

        Assert(IsA(pathnode, Path));

        return false; /* childless Result */

      }

    case T_Append:

      {

        AppendPath *appendPath = castNode(AppendPath, pathnode);

        /*

         * If there's exactly one child, then there will be no Append

         * in the final plan, so we can handle mark/restore if the

         * child plan node can.

         */

        if (list_length(appendPath->subpaths) == 1)

          return ExecSupportsMarkRestore((Path *) linitial(appendPath->subpaths));

        /* Otherwise, Append can't handle it */

        return false;

      }

    case T_MergeAppend:

      {

        MergeAppendPath *mapath = castNode(MergeAppendPath, pathnode);

        /*

         * Like the Append case above, single-subpath MergeAppends

         * won't be in the final plan, so just return the child's

         * mark/restore ability.

         */

        if (list_length(mapath->subpaths) == 1)

          return ExecSupportsMarkRestore((Path *) linitial(mapath->subpaths));

        /* Otherwise, MergeAppend can't handle it */

        return false;

      }

    default:

      break;

  }

  return false;

}

/*

 * ExecSupportsBackwardScan - does a plan type support backwards scanning?

 *

 * Ideally, all plan types would support backwards scan, but that seems

 * unlikely to happen soon.  In some cases, a plan node passes the backwards

 * scan down to its children, and so supports backwards scan only if its

 * children do.  Therefore, this routine must be passed a complete plan tree.

 */

bool

ExecSupportsBackwardScan(Plan *node)

{

  if (node == NULL)

    return false;

  /*

   * Parallel-aware nodes return a subset of the tuples in each worker, and

   * in general we can't expect to have enough bookkeeping state to know

   * which ones we returned in this worker as opposed to some other worker.

   */

  if (node->parallel_aware)

    return false;

  switch (nodeTag(node))

  {

    case T_Result:

      if (outerPlan(node) != NULL)

        return ExecSupportsBackwardScan(outerPlan(node));

      else

        return false;

    case T_Append:

      {

        ListCell   *l;

        /* With async, tuples may be interleaved, so can't back up. */

        if (((Append *) node)->nasyncplans > 0)

          return false;

        foreach(l, ((Append *) node)->appendplans)

        {

          if (!ExecSupportsBackwardScan((Plan *) lfirst(l)))

            return false;

        }

        /* need not check tlist because Append doesn't evaluate it */

        return true;

      }

    case T_SampleScan:

      /* Simplify life for tablesample methods by disallowing this */

      return false;

    case T_Gather:

      return false;

    case T_IndexScan:

      return IndexSupportsBackwardScan(((IndexScan *) node)->indexid);

    case T_IndexOnlyScan:

      return IndexSupportsBackwardScan(((IndexOnlyScan *) node)->indexid);

    case T_SubqueryScan:

      return ExecSupportsBackwardScan(((SubqueryScan *) node)->subplan);

    case T_CustomScan:

      if (((CustomScan *) node)->flags & CUSTOMPATH_SUPPORT_BACKWARD_SCAN)

        return true;

      return false;

    case T_SeqScan:

    case T_TidScan:

    case T_TidRangeScan:

    case T_FunctionScan:

    case T_ValuesScan:

    case T_CteScan:

    case T_Material:

    case T_Sort:

      /* these don't evaluate tlist */

      return true;

    case T_IncrementalSort:

      /*

       * Unlike full sort, incremental sort keeps only a single group of

       * tuples in memory, so it can't scan backwards.

       */

      return false;

    case T_LockRows:

    case T_Limit:

      return ExecSupportsBackwardScan(outerPlan(node));

    default:

      return false;

  }

}

/*

 * An IndexScan or IndexOnlyScan node supports backward scan only if the

 * index's AM does.

 */

static bool

IndexSupportsBackwardScan(Oid indexid)

{

  bool    result;

  HeapTuple ht_idxrel;

  Form_pg_class idxrelrec;

  IndexAmRoutine *amroutine;

  /* Fetch the pg_class tuple of the index relation */

  ht_idxrel = SearchSysCache1(RELOID, ObjectIdGetDatum(indexid));

  if (!HeapTupleIsValid(ht_idxrel))

    elog(ERROR, "cache lookup failed for relation %u", indexid);

  idxrelrec = (Form_pg_class) GETSTRUCT(ht_idxrel);

  /* Fetch the index AM's API struct */

  amroutine = GetIndexAmRoutineByAmId(idxrelrec->relam, false);

  result = amroutine->amcanbackward;

  pfree(amroutine);

  ReleaseSysCache(ht_idxrel);

  return result;

}

/*

 * ExecMaterializesOutput - does a plan type materialize its output?

 *

 * Returns true if the plan node type is one that automatically materializes

 * its output (typically by keeping it in a tuplestore).  For such plans,

 * a rescan without any parameter change will have zero startup cost and

 * very low per-tuple cost.

 */

bool

ExecMaterializesOutput(NodeTag plantype)

{

  switch (plantype)

  {

    case T_Material:

    case T_FunctionScan:

    case T_TableFuncScan:

    case T_CteScan:

    case T_NamedTuplestoreScan:

    case T_WorkTableScan:

    case T_Sort:

      return true;

    default:

      break;

  }

  return false;

}