/*-------------------------------------------------------------------------
 *
 * 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;
 }
}