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

 *

 * ginlogic.c

 *    routines for performing binary- and ternary-logic consistent checks.

 *

 * A GIN operator class can provide a boolean or ternary consistent

 * function, or both.  This file provides both boolean and ternary

 * interfaces to the rest of the GIN code, even if only one of them is

 * implemented by the opclass.

 *

 * Providing a boolean interface when the opclass implements only the

 * ternary function is straightforward - just call the ternary function

 * with the check-array as is, and map the GIN_TRUE, GIN_FALSE, GIN_MAYBE

 * return codes to TRUE, FALSE and TRUE+recheck, respectively.  Providing

 * a ternary interface when the opclass only implements a boolean function

 * is implemented by calling the boolean function many times, with all the

 * MAYBE arguments set to all combinations of TRUE and FALSE (up to a

 * certain number of MAYBE arguments).

 *

 * (A boolean function is enough to determine if an item matches, but a

 * GIN scan can apply various optimizations if it can determine that an

 * item matches or doesn't match, even if it doesn't know if some of the

 * keys are present or not.  That's what the ternary consistent function

 * is used for.)

 *

 *

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

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

 *

 * IDENTIFICATION

 *      src/backend/access/gin/ginlogic.c

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

 */

#include "postgres.h"

#include "access/gin_private.h"

/*

 * Maximum number of MAYBE inputs that shimTriConsistentFn will try to

 * resolve by calling all combinations.

 */

#define MAX_MAYBE_ENTRIES 4

/*

 * Dummy consistent functions for an EVERYTHING key.  Just claim it matches.

 */

static bool

trueConsistentFn(GinScanKey key)

{

  key->recheckCurItem = false;

  return true;

}

static GinTernaryValue

trueTriConsistentFn(GinScanKey key)

{

  return GIN_TRUE;

}

/*

 * A helper function for calling a regular, binary logic, consistent function.

 */

static bool

directBoolConsistentFn(GinScanKey key)

{

  /*

   * Initialize recheckCurItem in case the consistentFn doesn't know it

   * should set it.  The safe assumption in that case is to force recheck.

   */

  key->recheckCurItem = true;

  return DatumGetBool(FunctionCall8Coll(key->consistentFmgrInfo,

                      key->collation,

                      PointerGetDatum(key->entryRes),

                      UInt16GetDatum(key->strategy),

                      key->query,

                      UInt32GetDatum(key->nuserentries),

                      PointerGetDatum(key->extra_data),

                      PointerGetDatum(&key->recheckCurItem),

                      PointerGetDatum(key->queryValues),

                      PointerGetDatum(key->queryCategories)));

}

/*

 * A helper function for calling a native ternary logic consistent function.

 */

static GinTernaryValue

directTriConsistentFn(GinScanKey key)

{

  return DatumGetGinTernaryValue(FunctionCall7Coll(key->triConsistentFmgrInfo,

                           key->collation,

                           PointerGetDatum(key->entryRes),

                           UInt16GetDatum(key->strategy),

                           key->query,

                           UInt32GetDatum(key->nuserentries),

                           PointerGetDatum(key->extra_data),

                           PointerGetDatum(key->queryValues),

                           PointerGetDatum(key->queryCategories)));

}

/*

 * This function implements a binary logic consistency check, using a ternary

 * logic consistent function provided by the opclass. GIN_MAYBE return value

 * is interpreted as true with recheck flag.

 */

static bool

shimBoolConsistentFn(GinScanKey key)

{

  GinTernaryValue result;

  result = DatumGetGinTernaryValue(FunctionCall7Coll(key->triConsistentFmgrInfo,

                             key->collation,

                             PointerGetDatum(key->entryRes),

                             UInt16GetDatum(key->strategy),

                             key->query,

                             UInt32GetDatum(key->nuserentries),

                             PointerGetDatum(key->extra_data),

                             PointerGetDatum(key->queryValues),

                             PointerGetDatum(key->queryCategories)));

  if (result == GIN_MAYBE)

  {

    key->recheckCurItem = true;

    return true;

  }

  else

  {

    key->recheckCurItem = false;

    return result;

  }

}

/*

 * This function implements a tri-state consistency check, using a boolean

 * consistent function provided by the opclass.

 *

 * Our strategy is to call consistentFn with MAYBE inputs replaced with every

 * combination of TRUE/FALSE. If consistentFn returns the same value for every

 * combination, that's the overall result. Otherwise, return MAYBE. Testing

 * every combination is O(n^2), so this is only feasible for a small number of

 * MAYBE inputs.

 *

 * NB: This function modifies the key->entryRes array.  For now that's okay

 * so long as we restore the entry-time contents before returning.  This may

 * need revisiting if we ever invent multithreaded GIN scans, though.

 */

static GinTernaryValue

shimTriConsistentFn(GinScanKey key)

{

  int     nmaybe;

  int     maybeEntries[MAX_MAYBE_ENTRIES];

  int     i;

  bool    boolResult;

  bool    recheck;

  GinTernaryValue curResult;

  /*

   * Count how many MAYBE inputs there are, and store their indexes in

   * maybeEntries. If there are too many MAYBE inputs, it's not feasible to

   * test all combinations, so give up and return MAYBE.

   */

  nmaybe = 0;

  for (i = 0; i < key->nentries; i++)

  {

    if (key->entryRes[i] == GIN_MAYBE)

    {

      if (nmaybe >= MAX_MAYBE_ENTRIES)

        return GIN_MAYBE;

      maybeEntries[nmaybe++] = i;

    }

  }

  /*

   * If none of the inputs were MAYBE, we can just call the consistent

   * function as-is.

   */

  if (nmaybe == 0)

    return directBoolConsistentFn(key);

  /* First call consistent function with all the maybe-inputs set FALSE */

  for (i = 0; i < nmaybe; i++)

    key->entryRes[maybeEntries[i]] = GIN_FALSE;

  curResult = directBoolConsistentFn(key);

  recheck = key->recheckCurItem;

  for (;;)

  {

    /* Twiddle the entries for next combination. */

    for (i = 0; i < nmaybe; i++)

    {

      if (key->entryRes[maybeEntries[i]] == GIN_FALSE)

      {

        key->entryRes[maybeEntries[i]] = GIN_TRUE;

        break;

      }

      else

        key->entryRes[maybeEntries[i]] = GIN_FALSE;

    }

    if (i == nmaybe)

      break;

    boolResult = directBoolConsistentFn(key);

    recheck |= key->recheckCurItem;

    if (curResult != boolResult)

    {

      curResult = GIN_MAYBE;

      break;

    }

  }

  /* TRUE with recheck is taken to mean MAYBE */

  if (curResult == GIN_TRUE && recheck)

    curResult = GIN_MAYBE;

  /* We must restore the original state of the entryRes array */

  for (i = 0; i < nmaybe; i++)

    key->entryRes[maybeEntries[i]] = GIN_MAYBE;

  return curResult;

}

/*

 * Set up the implementation of the consistent functions for a scan key.

 */

void

ginInitConsistentFunction(GinState *ginstate, GinScanKey key)

{

  if (key->searchMode == GIN_SEARCH_MODE_EVERYTHING)

  {

    key->boolConsistentFn = trueConsistentFn;

    key->triConsistentFn = trueTriConsistentFn;

  }

  else

  {

    key->consistentFmgrInfo = &ginstate->consistentFn[key->attnum - 1];

    key->triConsistentFmgrInfo = &ginstate->triConsistentFn[key->attnum - 1];

    key->collation = ginstate->supportCollation[key->attnum - 1];

    if (OidIsValid(ginstate->consistentFn[key->attnum - 1].fn_oid))

      key->boolConsistentFn = directBoolConsistentFn;

    else

      key->boolConsistentFn = shimBoolConsistentFn;

    if (OidIsValid(ginstate->triConsistentFn[key->attnum - 1].fn_oid))

      key->triConsistentFn = directTriConsistentFn;

    else

      key->triConsistentFn = shimTriConsistentFn;

  }

}