Still more fixes for lossy-GiST-distance-functions patch.

Fix confusion in documentation, substantial memory leakage if float8 or
float4 are pass-by-reference, and assorted comments that were obsoleted
by commit 98edd617f3.

doc/src/sgml/gist.sgml

@@ -208,12 +208,6 @@
    </tgroup>
   </table>
 
- <para>
-  Currently, ordering by the distance operator <literal>&lt;-&gt;</>
-  is supported only with <literal>point</> by the operator classes
-  of the geometric types.
- </para>
-
  <para>
   For historical reasons, the <literal>inet_ops</> operator class is
   not the default class for types <type>inet</> and <type>cidr</>.
@@ -805,28 +799,30 @@ my_distance(PG_FUNCTION_ARGS)
       </para>
 
       <para>
-       Some approximation is allowed when determining the distance, as long as
+       Some approximation is allowed when determining the distance, so long
-       the result is never greater than the entry's actual distance. Thus, for
+       as the result is never greater than the entry's actual distance. Thus,
-       example, distance to a bounding box is usually sufficient in geometric
+       for example, distance to a bounding box is usually sufficient in
-       applications.  For an internal tree node, the distance returned must not
+       geometric applications.  For an internal tree node, the distance
-       be greater than the distance to any of the child nodes. If the returned
+       returned must not be greater than the distance to any of the child
-       distance is not accurate, the function must set *recheck to false. (This
+       nodes. If the returned distance is not exact, the function must set
-       is not necessary for internal tree nodes; for them, the calculation is
+       <literal>*recheck</> to true. (This is not necessary for internal tree
-       always assumed to be inaccurate). The executor will calculate the
+       nodes; for them, the calculation is always assumed to be inexact.) In
-       accurate distance after fetching the tuple from the heap, and reorder
+       this case the executor will calculate the accurate distance after
-       the tuples if necessary.
+       fetching the tuple from the heap, and reorder the tuples if necessary.
       </para>
 
       <para>
-       If the distance function returns *recheck=true for a leaf node, the
+       If the distance function returns <literal>*recheck = true</> for any
-       original ordering operator's return type must be float8 or float4, and
+       leaf node, the original ordering operator's return type must
-       the distance function's return value must be comparable with the actual
+       be <type>float8</> or <type>float4</>, and the distance function's
-       distance operator. Otherwise, the distance function's return type can
+       result values must be comparable to those of the original ordering
-       be any finit <type>float8</> value, as long as the relative order of
+       operator, since the executor will sort using both distance function
-       the returned values matches the order returned by the ordering operator.
+       results and recalculated ordering-operator results.  Otherwise, the
-       (Infinity and minus infinity are used internally to handle cases such as
+       distance function's result values can be any finite <type>float8</>
-       nulls, so it is not recommended that <function>distance</> functions
+       values, so long as the relative order of the result values matches the
-       return these values.)
+       order returned by the ordering operator.  (Infinity and minus infinity
+       are used internally to handle cases such as nulls, so it is not
+       recommended that <function>distance</> functions return these values.)
       </para>
 
      </listitem>

src/backend/access/gist/gistget.c

@@ -191,20 +191,18 @@ gistindex_keytest(IndexScanDesc scan,
 			/*
 			 * Call the Distance function to evaluate the distance.  The
 			 * arguments are the index datum (as a GISTENTRY*), the comparison
-			 * datum, and the ordering operator's strategy number and subtype
+			 * datum, the ordering operator's strategy number and subtype from
-			 * from pg_amop.
+			 * pg_amop, and the recheck flag.
 			 *
 			 * (Presently there's no need to pass the subtype since it'll
 			 * always be zero, but might as well pass it for possible future
 			 * use.)
 			 *
-			 * Distance functions get a recheck argument as well.  In this
+			 * If the function sets the recheck flag, the returned distance is
-			 * case the returned distance is the lower bound of distance and
+			 * a lower bound on the true distance and needs to be rechecked.
-			 * needs to be rechecked.  We return single recheck flag which
+			 * We initialize the flag to 'false'.  This flag was added in
-			 * means that both quals and distances are to be rechecked.  We
+			 * version 9.5; distance functions written before that won't know
-			 * initialize the flag to 'false'.  The flag was added in version
+			 * about the flag, but are expected to never be lossy.
-			 * 9.5 and the distance operators written before that won't know
-			 * about the flag, and are never lossy.
 			 */
 			recheck = false;
 			dist = FunctionCall5Coll(&key->sk_func,
@@ -475,11 +473,22 @@ getNextNearest(IndexScanDesc scan)
 			{
 				if (so->orderByTypes[i] == FLOAT8OID)
 				{
+#ifndef USE_FLOAT8_BYVAL
+					/* must free any old value to avoid memory leakage */
+					if (!scan->xs_orderbynulls[i])
+						pfree(DatumGetPointer(scan->xs_orderbyvals[i]));
+#endif
 					scan->xs_orderbyvals[i] = Float8GetDatum(item->distances[i]);
 					scan->xs_orderbynulls[i] = false;
 				}
 				else if (so->orderByTypes[i] == FLOAT4OID)
 				{
+					/* convert distance function's result to ORDER BY type */
+#ifndef USE_FLOAT4_BYVAL
+					/* must free any old value to avoid memory leakage */
+					if (!scan->xs_orderbynulls[i])
+						pfree(DatumGetPointer(scan->xs_orderbyvals[i]));
+#endif
 					scan->xs_orderbyvals[i] = Float4GetDatum((float4) item->distances[i]);
 					scan->xs_orderbynulls[i] = false;
 				}
@@ -491,7 +500,7 @@ getNextNearest(IndexScanDesc scan)
 					 * calculated by the distance function to that.  The
 					 * executor won't actually need the order by values we
 					 * return here, if there are no lossy results, so only
-					 * insist on the datatype if the *recheck is set.
+					 * insist on converting if the *recheck flag is set.
 					 */
 					if (scan->xs_recheckorderby)
 						elog(ERROR, "GiST operator family's FOR ORDER BY operator must return float8 or float4 if the distance function is lossy");

src/backend/access/gist/gistscan.c

@@ -88,8 +88,9 @@ gistbeginscan(PG_FUNCTION_ARGS)
 	so->qual_ok = true;			/* in case there are zero keys */
 	if (scan->numberOfOrderBys > 0)
 	{
-		scan->xs_orderbyvals = palloc(sizeof(Datum) * scan->numberOfOrderBys);
+		scan->xs_orderbyvals = palloc0(sizeof(Datum) * scan->numberOfOrderBys);
 		scan->xs_orderbynulls = palloc(sizeof(bool) * scan->numberOfOrderBys);
+		memset(scan->xs_orderbynulls, true, sizeof(bool) * scan->numberOfOrderBys);
 	}
 
 	scan->opaque = so;
@@ -284,6 +285,8 @@ gistrescan(PG_FUNCTION_ARGS)
 					 GIST_DISTANCE_PROC, skey->sk_attno,
 					 RelationGetRelationName(scan->indexRelation));
 
+			fmgr_info_copy(&(skey->sk_func), finfo, so->giststate->scanCxt);
+
 			/*
 			 * Look up the datatype returned by the original ordering operator.
 			 * GiST always uses a float8 for the distance function, but the
@@ -297,7 +300,6 @@ gistrescan(PG_FUNCTION_ARGS)
 			 * first time.
 			 */
 			so->orderByTypes[i] = get_func_rettype(skey->sk_func.fn_oid);
-			fmgr_info_copy(&(skey->sk_func), finfo, so->giststate->scanCxt);
 
 			/* Restore prior fn_extra pointers, if not first time */
 			if (!first_time)

src/backend/executor/nodeIndexscan.c

@@ -459,10 +459,16 @@ reorderqueue_pop(IndexScanState *node)
 {
 	HeapTuple	result;
 	ReorderTuple *topmost;
+	int			i;
 
 	topmost = (ReorderTuple *) pairingheap_remove_first(node->iss_ReorderQueue);
 
 	result = topmost->htup;
+	for (i = 0; i < node->iss_NumOrderByKeys; i++)
+	{
+		if (!node->iss_OrderByTypByVals[i] && !topmost->orderbynulls[i])
+			pfree(DatumGetPointer(topmost->orderbyvals[i]));
+	}
 	pfree(topmost->orderbyvals);
 	pfree(topmost->orderbynulls);
 	pfree(topmost);

src/include/access/relscan.h

@@ -95,12 +95,13 @@ typedef struct IndexScanDescData
 	/*
 	 * When fetching with an ordering operator, the values of the ORDER BY
 	 * expressions of the last returned tuple, according to the index.  If
-	 * xs_recheck is true, these need to be rechecked just like the scan keys,
+	 * xs_recheckorderby is true, these need to be rechecked just like the
-	 * and the values returned here are a lower-bound on the actual values.
+	 * scan keys, and the values returned here are a lower-bound on the actual
+	 * values.
 	 */
 	Datum	   *xs_orderbyvals;
 	bool	   *xs_orderbynulls;
-	bool		xs_recheckorderby;	/* T means ORDER BY exprs must be rechecked */
+	bool		xs_recheckorderby;
 
 	/* state data for traversing HOT chains in index_getnext */
 	bool		xs_continue_hot;	/* T if must keep walking HOT chain */