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

 *

 * nodeNestloop.c

 *    routines to support nest-loop joins

 *

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

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

 *

 *

 * IDENTIFICATION

 *    src/backend/executor/nodeNestloop.c

 *

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

 */

/*

 *   INTERFACE ROUTINES

 *    ExecNestLoop   - process a nestloop join of two plans

 *    ExecInitNestLoop - initialize the join

 *    ExecEndNestLoop  - shut down the join

 */

#include "postgres.h"

#include "executor/execdebug.h"

#include "executor/nodeNestloop.h"

#include "miscadmin.h"

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

 *    ExecNestLoop(node)

 *

 * old comments

 *    Returns the tuple joined from inner and outer tuples which

 *    satisfies the qualification clause.

 *

 *    It scans the inner relation to join with current outer tuple.

 *

 *    If none is found, next tuple from the outer relation is retrieved

 *    and the inner relation is scanned from the beginning again to join

 *    with the outer tuple.

 *

 *    NULL is returned if all the remaining outer tuples are tried and

 *    all fail to join with the inner tuples.

 *

 *    NULL is also returned if there is no tuple from inner relation.

 *

 *    Conditions:

 *      -- outerTuple contains current tuple from outer relation and

 *       the right son(inner relation) maintains "cursor" at the tuple

 *       returned previously.

 *        This is achieved by maintaining a scan position on the outer

 *        relation.

 *

 *    Initial States:

 *      -- the outer child and the inner child

 *         are prepared to return the first tuple.

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

 */

static TupleTableSlot *

ExecNestLoop(PlanState *pstate)

{

  NestLoopState *node = castNode(NestLoopState, pstate);

  NestLoop   *nl;

  PlanState  *innerPlan;

  PlanState  *outerPlan;

  TupleTableSlot *outerTupleSlot;

  TupleTableSlot *innerTupleSlot;

  ExprState  *joinqual;

  ExprState  *otherqual;

  ExprContext *econtext;

  ListCell   *lc;

  CHECK_FOR_INTERRUPTS();

  /*

   * get information from the node

   */

  ENL1_printf("getting info from node");

  nl = (NestLoop *) node->js.ps.plan;

  joinqual = node->js.joinqual;

  otherqual = node->js.ps.qual;

  outerPlan = outerPlanState(node);

  innerPlan = innerPlanState(node);

  econtext = node->js.ps.ps_ExprContext;

  /*

   * Reset per-tuple memory context to free any expression evaluation

   * storage allocated in the previous tuple cycle.

   */

  ResetExprContext(econtext);

  /*

   * Ok, everything is setup for the join so now loop until we return a

   * qualifying join tuple.

   */

  ENL1_printf("entering main loop");

  for (;;)

  {

    /*

     * If we don't have an outer tuple, get the next one and reset the

     * inner scan.

     */

    if (node->nl_NeedNewOuter)

    {

      ENL1_printf("getting new outer tuple");

      outerTupleSlot = ExecProcNode(outerPlan);

      /*

       * if there are no more outer tuples, then the join is complete..

       */

      if (TupIsNull(outerTupleSlot))

      {

        ENL1_printf("no outer tuple, ending join");

        return NULL;

      }

      ENL1_printf("saving new outer tuple information");

      econtext->ecxt_outertuple = outerTupleSlot;

      node->nl_NeedNewOuter = false;

      node->nl_MatchedOuter = false;

      /*

       * fetch the values of any outer Vars that must be passed to the

       * inner scan, and store them in the appropriate PARAM_EXEC slots.

       */

      foreach(lc, nl->nestParams)

      {

        NestLoopParam *nlp = (NestLoopParam *) lfirst(lc);

        int     paramno = nlp->paramno;

        ParamExecData *prm;

        prm = &(econtext->ecxt_param_exec_vals[paramno]);

        /* Param value should be an OUTER_VAR var */

        Assert(IsA(nlp->paramval, Var));

        Assert(nlp->paramval->varno == OUTER_VAR);

        Assert(nlp->paramval->varattno > 0);

        prm->value = slot_getattr(outerTupleSlot,

                      nlp->paramval->varattno,

                      &(prm->isnull));

        /* Flag parameter value as changed */

        innerPlan->chgParam = bms_add_member(innerPlan->chgParam,

                           paramno);

      }

      /*

       * now rescan the inner plan

       */

      ENL1_printf("rescanning inner plan");

      ExecReScan(innerPlan);

    }

    /*

     * we have an outerTuple, try to get the next inner tuple.

     */

    ENL1_printf("getting new inner tuple");

    innerTupleSlot = ExecProcNode(innerPlan);

    econtext->ecxt_innertuple = innerTupleSlot;

    if (TupIsNull(innerTupleSlot))

    {

      ENL1_printf("no inner tuple, need new outer tuple");

      node->nl_NeedNewOuter = true;

      if (!node->nl_MatchedOuter &&

        (node->js.jointype == JOIN_LEFT ||

         node->js.jointype == JOIN_ANTI))

      {

        /*

         * We are doing an outer join and there were no join matches

         * for this outer tuple.  Generate a fake join tuple with

         * nulls for the inner tuple, and return it if it passes the

         * non-join quals.

         */

        econtext->ecxt_innertuple = node->nl_NullInnerTupleSlot;

        ENL1_printf("testing qualification for outer-join tuple");

        if (otherqual == NULL || ExecQual(otherqual, econtext))

        {

          /*

           * qualification was satisfied so we project and return

           * the slot containing the result tuple using

           * ExecProject().

           */

          ENL1_printf("qualification succeeded, projecting tuple");

          return ExecProject(node->js.ps.ps_ProjInfo);

        }

        else

          InstrCountFiltered2(node, 1);

      }

      /*

       * Otherwise just return to top of loop for a new outer tuple.

       */

      continue;

    }

    /*

     * at this point we have a new pair of inner and outer tuples so we

     * test the inner and outer tuples to see if they satisfy the node's

     * qualification.

     *

     * Only the joinquals determine MatchedOuter status, but all quals

     * must pass to actually return the tuple.

     */

    ENL1_printf("testing qualification");

    if (ExecQual(joinqual, econtext))

    {

      node->nl_MatchedOuter = true;

      /* In an antijoin, we never return a matched tuple */

      if (node->js.jointype == JOIN_ANTI)

      {

        node->nl_NeedNewOuter = true;

        continue;   /* return to top of loop */

      }

      /*

       * If we only need to join to the first matching inner tuple, then

       * consider returning this one, but after that continue with next

       * outer tuple.

       */

      if (node->js.single_match)

        node->nl_NeedNewOuter = true;

      if (otherqual == NULL || ExecQual(otherqual, econtext))

      {

        /*

         * qualification was satisfied so we project and return the

         * slot containing the result tuple using ExecProject().

         */

        ENL1_printf("qualification succeeded, projecting tuple");

        return ExecProject(node->js.ps.ps_ProjInfo);

      }

      else

        InstrCountFiltered2(node, 1);

    }

    else

      InstrCountFiltered1(node, 1);

    /*

     * Tuple fails qual, so free per-tuple memory and try again.

     */

    ResetExprContext(econtext);

    ENL1_printf("qualification failed, looping");

  }

}

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

 *    ExecInitNestLoop

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

 */

NestLoopState *

ExecInitNestLoop(NestLoop *node, EState *estate, int eflags)

{

  NestLoopState *nlstate;

  /* check for unsupported flags */

  Assert(!(eflags & (EXEC_FLAG_BACKWARD | EXEC_FLAG_MARK)));

  NL1_printf("ExecInitNestLoop: %s\n",

         "initializing node");

  /*

   * create state structure

   */

  nlstate = makeNode(NestLoopState);

  nlstate->js.ps.plan = (Plan *) node;

  nlstate->js.ps.state = estate;

  nlstate->js.ps.ExecProcNode = ExecNestLoop;

  /*

   * Miscellaneous initialization

   *

   * create expression context for node

   */

  ExecAssignExprContext(estate, &nlstate->js.ps);

  /*

   * initialize child nodes

   *

   * If we have no parameters to pass into the inner rel from the outer,

   * tell the inner child that cheap rescans would be good.  If we do have

   * such parameters, then there is no point in REWIND support at all in the

   * inner child, because it will always be rescanned with fresh parameter

   * values.

   */

  outerPlanState(nlstate) = ExecInitNode(outerPlan(node), estate, eflags);

  if (node->nestParams == NIL)

    eflags |= EXEC_FLAG_REWIND;

  else

    eflags &= ~EXEC_FLAG_REWIND;

  innerPlanState(nlstate) = ExecInitNode(innerPlan(node), estate, eflags);

  /*

   * Initialize result slot, type and projection.

   */

  ExecInitResultTupleSlotTL(&nlstate->js.ps, &TTSOpsVirtual);

  ExecAssignProjectionInfo(&nlstate->js.ps, NULL);

  /*

   * initialize child expressions

   */

  nlstate->js.ps.qual =

    ExecInitQual(node->join.plan.qual, (PlanState *) nlstate);

  nlstate->js.jointype = node->join.jointype;

  nlstate->js.joinqual =

    ExecInitQual(node->join.joinqual, (PlanState *) nlstate);

  /*

   * detect whether we need only consider the first matching inner tuple

   */

  nlstate->js.single_match = (node->join.inner_unique ||

                node->join.jointype == JOIN_SEMI);

  /* set up null tuples for outer joins, if needed */

  switch (node->join.jointype)

  {

    case JOIN_INNER:

    case JOIN_SEMI:

      break;

    case JOIN_LEFT:

    case JOIN_ANTI:

      nlstate->nl_NullInnerTupleSlot =

        ExecInitNullTupleSlot(estate,

                    ExecGetResultType(innerPlanState(nlstate)),

                    &TTSOpsVirtual);

      break;

    default:

      elog(ERROR, "unrecognized join type: %d",

         (int) node->join.jointype);

  }

  /*

   * finally, wipe the current outer tuple clean.

   */

  nlstate->nl_NeedNewOuter = true;

  nlstate->nl_MatchedOuter = false;

  NL1_printf("ExecInitNestLoop: %s\n",

         "node initialized");

  return nlstate;

}

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

 *    ExecEndNestLoop

 *

 *    closes down scans and frees allocated storage

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

 */

void

ExecEndNestLoop(NestLoopState *node)

{

  NL1_printf("ExecEndNestLoop: %s\n",

         "ending node processing");

  /*

   * close down subplans

   */

  ExecEndNode(outerPlanState(node));

  ExecEndNode(innerPlanState(node));

  NL1_printf("ExecEndNestLoop: %s\n",

         "node processing ended");

}

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

 *    ExecReScanNestLoop

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

 */

void

ExecReScanNestLoop(NestLoopState *node)

{

  PlanState  *outerPlan = outerPlanState(node);

  /*

   * If outerPlan->chgParam is not null then plan will be automatically

   * re-scanned by first ExecProcNode.

   */

  if (outerPlan->chgParam == NULL)

    ExecReScan(outerPlan);

  /*

   * innerPlan is re-scanned for each new outer tuple and MUST NOT be

   * re-scanned from here or you'll get troubles from inner index scans when

   * outer Vars are used as run-time keys...

   */

  node->nl_NeedNewOuter = true;

  node->nl_MatchedOuter = false;

}