Branch data Line data Source code
1 : : /*-------------------------------------------------------------------------
2 : : *
3 : : * ginlogic.c
4 : : * routines for performing binary- and ternary-logic consistent checks.
5 : : *
6 : : * A GIN operator class can provide a boolean or ternary consistent
7 : : * function, or both. This file provides both boolean and ternary
8 : : * interfaces to the rest of the GIN code, even if only one of them is
9 : : * implemented by the opclass.
10 : : *
11 : : * Providing a boolean interface when the opclass implements only the
12 : : * ternary function is straightforward - just call the ternary function
13 : : * with the check-array as is, and map the GIN_TRUE, GIN_FALSE, GIN_MAYBE
14 : : * return codes to TRUE, FALSE and TRUE+recheck, respectively. Providing
15 : : * a ternary interface when the opclass only implements a boolean function
16 : : * is implemented by calling the boolean function many times, with all the
17 : : * MAYBE arguments set to all combinations of TRUE and FALSE (up to a
18 : : * certain number of MAYBE arguments).
19 : : *
20 : : * (A boolean function is enough to determine if an item matches, but a
21 : : * GIN scan can apply various optimizations if it can determine that an
22 : : * item matches or doesn't match, even if it doesn't know if some of the
23 : : * keys are present or not. That's what the ternary consistent function
24 : : * is used for.)
25 : : *
26 : : *
27 : : * Portions Copyright (c) 1996-2026, PostgreSQL Global Development Group
28 : : * Portions Copyright (c) 1994, Regents of the University of California
29 : : *
30 : : * IDENTIFICATION
31 : : * src/backend/access/gin/ginlogic.c
32 : : *-------------------------------------------------------------------------
33 : : */
34 : :
35 : : #include "postgres.h"
36 : :
37 : : #include "access/gin_private.h"
38 : :
39 : :
40 : : /*
41 : : * Maximum number of MAYBE inputs that shimTriConsistentFn will try to
42 : : * resolve by calling all combinations.
43 : : */
44 : : #define MAX_MAYBE_ENTRIES 4
45 : :
46 : : /*
47 : : * Dummy consistent functions for an EVERYTHING key. Just claim it matches.
48 : : */
49 : : static bool
50 : 0 : trueConsistentFn(GinScanKey key)
51 : : {
52 : 0 : key->recheckCurItem = false;
53 : 0 : return true;
54 : : }
55 : : static GinTernaryValue
56 : 0 : trueTriConsistentFn(GinScanKey key)
57 : : {
58 : 0 : return GIN_TRUE;
59 : : }
60 : :
61 : : /*
62 : : * A helper function for calling a regular, binary logic, consistent function.
63 : : */
64 : : static bool
65 : 19417 : directBoolConsistentFn(GinScanKey key)
66 : : {
67 : : /*
68 : : * Initialize recheckCurItem in case the consistentFn doesn't know it
69 : : * should set it. The safe assumption in that case is to force recheck.
70 : : */
71 : 19417 : key->recheckCurItem = true;
72 : :
73 : 19417 : return DatumGetBool(FunctionCall8Coll(key->consistentFmgrInfo,
74 : : key->collation,
75 : 19417 : PointerGetDatum(key->entryRes),
76 : 19417 : UInt16GetDatum(key->strategy),
77 : : key->query,
78 : 19417 : Int32GetDatum(key->nuserentries),
79 : 19417 : PointerGetDatum(key->extra_data),
80 : 19417 : PointerGetDatum(&key->recheckCurItem),
81 : 19417 : PointerGetDatum(key->queryValues),
82 : 19417 : PointerGetDatum(key->queryCategories)));
83 : : }
84 : :
85 : : /*
86 : : * A helper function for calling a native ternary logic consistent function.
87 : : */
88 : : static GinTernaryValue
89 : 612653 : directTriConsistentFn(GinScanKey key)
90 : : {
91 : 612653 : return DatumGetGinTernaryValue(FunctionCall7Coll(key->triConsistentFmgrInfo,
92 : : key->collation,
93 : 612653 : PointerGetDatum(key->entryRes),
94 : 612653 : UInt16GetDatum(key->strategy),
95 : : key->query,
96 : 612653 : Int32GetDatum(key->nuserentries),
97 : 612653 : PointerGetDatum(key->extra_data),
98 : 612653 : PointerGetDatum(key->queryValues),
99 : 612653 : PointerGetDatum(key->queryCategories)));
100 : : }
101 : :
102 : : /*
103 : : * This function implements a binary logic consistency check, using a ternary
104 : : * logic consistent function provided by the opclass. GIN_MAYBE return value
105 : : * is interpreted as true with recheck flag.
106 : : */
107 : : static bool
108 : 0 : shimBoolConsistentFn(GinScanKey key)
109 : : {
110 : : GinTernaryValue result;
111 : :
112 : 0 : result = DatumGetGinTernaryValue(FunctionCall7Coll(key->triConsistentFmgrInfo,
113 : : key->collation,
114 : 0 : PointerGetDatum(key->entryRes),
115 : 0 : UInt16GetDatum(key->strategy),
116 : : key->query,
117 : 0 : Int32GetDatum(key->nuserentries),
118 : 0 : PointerGetDatum(key->extra_data),
119 : 0 : PointerGetDatum(key->queryValues),
120 : 0 : PointerGetDatum(key->queryCategories)));
121 [ # # ]: 0 : if (result == GIN_MAYBE)
122 : : {
123 : 0 : key->recheckCurItem = true;
124 : 0 : return true;
125 : : }
126 : : else
127 : : {
128 : 0 : key->recheckCurItem = false;
129 : 0 : return result;
130 : : }
131 : : }
132 : :
133 : : /*
134 : : * This function implements a tri-state consistency check, using a boolean
135 : : * consistent function provided by the opclass.
136 : : *
137 : : * Our strategy is to call consistentFn with MAYBE inputs replaced with every
138 : : * combination of TRUE/FALSE. If consistentFn returns the same value for every
139 : : * combination, that's the overall result. Otherwise, return MAYBE. Testing
140 : : * every combination is O(n^2), so this is only feasible for a small number of
141 : : * MAYBE inputs.
142 : : *
143 : : * NB: This function modifies the key->entryRes array. For now that's okay
144 : : * so long as we restore the entry-time contents before returning. This may
145 : : * need revisiting if we ever invent multithreaded GIN scans, though.
146 : : */
147 : : static GinTernaryValue
148 : 18801 : shimTriConsistentFn(GinScanKey key)
149 : : {
150 : : int nmaybe;
151 : : uint32 maybeEntries[MAX_MAYBE_ENTRIES];
152 : : bool boolResult;
153 : : bool recheck;
154 : : GinTernaryValue curResult;
155 : :
156 : : /*
157 : : * Count how many MAYBE inputs there are, and store their indexes in
158 : : * maybeEntries. If there are too many MAYBE inputs, it's not feasible to
159 : : * test all combinations, so give up and return MAYBE.
160 : : */
161 : 18801 : nmaybe = 0;
162 [ + + ]: 71639 : for (uint32 i = 0; i < key->nentries; i++)
163 : : {
164 [ + + ]: 52838 : if (key->entryRes[i] == GIN_MAYBE)
165 : : {
166 [ - + ]: 38 : if (nmaybe >= MAX_MAYBE_ENTRIES)
167 : 0 : return GIN_MAYBE;
168 : 38 : maybeEntries[nmaybe++] = i;
169 : : }
170 : : }
171 : :
172 : : /*
173 : : * If none of the inputs were MAYBE, we can just call the consistent
174 : : * function as-is.
175 : : */
176 [ + + ]: 18801 : if (nmaybe == 0)
177 : 18775 : return directBoolConsistentFn(key);
178 : :
179 : : /* First call consistent function with all the maybe-inputs set FALSE */
180 [ + + ]: 64 : for (int i = 0; i < nmaybe; i++)
181 : 38 : key->entryRes[maybeEntries[i]] = GIN_FALSE;
182 : 26 : curResult = directBoolConsistentFn(key);
183 : 26 : recheck = key->recheckCurItem;
184 : :
185 : : for (;;)
186 : 42 : {
187 : : int i;
188 : :
189 : : /* Twiddle the entries for next combination. */
190 [ + + ]: 108 : for (i = 0; i < nmaybe; i++)
191 : : {
192 [ + + ]: 88 : if (key->entryRes[maybeEntries[i]] == GIN_FALSE)
193 : : {
194 : 48 : key->entryRes[maybeEntries[i]] = GIN_TRUE;
195 : 48 : break;
196 : : }
197 : : else
198 : 40 : key->entryRes[maybeEntries[i]] = GIN_FALSE;
199 : : }
200 [ + + ]: 68 : if (i == nmaybe)
201 : 20 : break;
202 : :
203 : 48 : boolResult = directBoolConsistentFn(key);
204 : 48 : recheck |= key->recheckCurItem;
205 : :
206 [ + + ]: 48 : if (curResult != boolResult)
207 : : {
208 : 6 : curResult = GIN_MAYBE;
209 : 6 : break;
210 : : }
211 : : }
212 : :
213 : : /* TRUE with recheck is taken to mean MAYBE */
214 [ + + + + ]: 26 : if (curResult == GIN_TRUE && recheck)
215 : 3 : curResult = GIN_MAYBE;
216 : :
217 : : /* We must restore the original state of the entryRes array */
218 [ + + ]: 64 : for (int i = 0; i < nmaybe; i++)
219 : 38 : key->entryRes[maybeEntries[i]] = GIN_MAYBE;
220 : :
221 : 26 : return curResult;
222 : : }
223 : :
224 : : /*
225 : : * Set up the implementation of the consistent functions for a scan key.
226 : : */
227 : : void
228 : 1229 : ginInitConsistentFunction(GinState *ginstate, GinScanKey key)
229 : : {
230 [ - + ]: 1229 : if (key->searchMode == GIN_SEARCH_MODE_EVERYTHING)
231 : : {
232 : 0 : key->boolConsistentFn = trueConsistentFn;
233 : 0 : key->triConsistentFn = trueTriConsistentFn;
234 : : }
235 : : else
236 : : {
237 : 1229 : key->consistentFmgrInfo = &ginstate->consistentFn[key->attnum - 1];
238 : 1229 : key->triConsistentFmgrInfo = &ginstate->triConsistentFn[key->attnum - 1];
239 : 1229 : key->collation = ginstate->supportCollation[key->attnum - 1];
240 : :
241 [ + - ]: 1229 : if (OidIsValid(ginstate->consistentFn[key->attnum - 1].fn_oid))
242 : 1229 : key->boolConsistentFn = directBoolConsistentFn;
243 : : else
244 : 0 : key->boolConsistentFn = shimBoolConsistentFn;
245 : :
246 [ + + ]: 1229 : if (OidIsValid(ginstate->triConsistentFn[key->attnum - 1].fn_oid))
247 : 883 : key->triConsistentFn = directTriConsistentFn;
248 : : else
249 : 346 : key->triConsistentFn = shimTriConsistentFn;
250 : : }
251 : 1229 : }
|
