From: Alvaro Herrera <alvherre@alvh.no-ip.org>
Date: Mon, 20 Jul 2015 10:16:40 +0000 (+0200)
Subject: Improve BRIN documentation somewhat
X-Git-Tag: REL9_5_ALPHA2~89
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=38b03caebc5de;p=postgresql

Improve BRIN documentation somewhat

This removes some info about support procedures being used, which was
obsoleted by commit db5f98ab4f, as well as add some more documentation
on how to create new opclasses using the Minmax infrastructure.
(Hopefully we can get something similar for Inclusion as well.)

In passing, fix some obsolete mentions of "mmtuples" in source code
comments.

Backpatch to 9.5, where BRIN was introduced.
---

diff --git a/doc/src/sgml/brin.sgml b/doc/src/sgml/brin.sgml
index cdfe5dec56..c8c3de72e3 100644
--- a/doc/src/sgml/brin.sgml
+++ b/doc/src/sgml/brin.sgml
@@ -529,14 +529,79 @@ typedef struct BrinOpcInfo
    </varlistentry>
   </variablelist>
 
-  To implement these methods in a generic way, the operator class
-  defines its own internal support functions.
-  (For instance, the <quote>min/max</> operator classes implement
-  support functions for the four inequality operators for their data type.)
-  Additionally, the operator class must supply appropriate
-  operator entries,
-  to enable the optimizer to use the index when those operators are
-  used in queries.
+  The core distribution includes support for two types of operator classes:
+  minmax and inclusion.  Operator class definitions using them are shipped for
+  in-core data types as appropriate.  Additional operator classes can be
+  defined by the user for other datatypes using equivalent definitions,
+  without having to write any source code; appropriate catalog entries being
+  declared is enough.  Note that assumptions about the semantics of operator
+  strategies are embedded in the support procedures's source code.
  </para>
+
+ <para>
+  Operator classes that implement completely different semantics are also
+  possible, provided implementations of the four main support procedures
+  described above are written.  Note that backwards compatibility across major
+  releases is not guaranteed: for example, additional support procedures might
+  be required in later releases.
+ </para>
+
+ <para>
+  To write an operator class for a datatype that implements a totally
+  ordered set, it is possible to use the Minmax support procedures
+  alongside the corresponding operators, as shown in
+  <xref linkend="brin-extensibility-minmax-table">.
+  All operator class members (procedures and operators) are mandatory.
+ </para>
+
+ <table id="brin-extensibility-minmax-table">
+  <title>Procedure and Support Numbers for Minmax Operator Classes</title>
+  <tgroup cols="2">
+   <thead>
+    <row>
+     <entry>Operator class member</entry>
+     <entry>Object</entry>
+    </row>
+   </thead>
+   <tbody>
+    <row>
+     <entry>Support Procedure 1</entry>
+     <entry>function <function>brin_minmax_opcinfo()</function></entry>
+    </row>
+    <row>
+     <entry>Support Procedure 2</entry>
+     <entry>function <function>brin_minmax_add_value()</function></entry>
+    </row>
+    <row>
+     <entry>Support Procedure 3</entry>
+     <entry>function <function>brin_minmax_consistent()</function></entry>
+    </row>
+    <row>
+     <entry>Support Procedure 4</entry>
+     <entry>function <function>brin_minmax_union()</function></entry>
+    </row>
+    <row>
+     <entry>Operator Strategy 1</entry>
+     <entry>operator less-than</entry>
+    </row>
+    <row>
+     <entry>Operator Strategy 2</entry>
+     <entry>operator less-than-or-equal-to</entry>
+    </row>
+    <row>
+     <entry>Operator Strategy 3</entry>
+     <entry>operator equal-to</entry>
+    </row>
+    <row>
+     <entry>Operator Strategy 4</entry>
+     <entry>operator greater-than-or-equal-to</entry>
+    </row>
+    <row>
+     <entry>Operator Strategy 5</entry>
+     <entry>operator greater-than</entry>
+    </row>
+   </tbody>
+  </tgroup>
+ </table>
 </sect1>
 </chapter>
diff --git a/src/backend/access/brin/brin.c b/src/backend/access/brin/brin.c
index ff18b220c2..268a55e71f 100644
--- a/src/backend/access/brin/brin.c
+++ b/src/backend/access/brin/brin.c
@@ -688,7 +688,7 @@ brinbuildempty(PG_FUNCTION_ARGS)
  *
  * XXX we could mark item tuples as "dirty" (when a minimum or maximum heap
  * tuple is deleted), meaning the need to re-run summarization on the affected
- * range.  Need to an extra flag in mmtuples for that.
+ * range.  Need to an extra flag in brintuples for that.
  */
 Datum
 brinbulkdelete(PG_FUNCTION_ARGS)
diff --git a/src/backend/access/brin/brin_xlog.c b/src/backend/access/brin/brin_xlog.c
index 0900155292..760f0daf02 100644
--- a/src/backend/access/brin/brin_xlog.c
+++ b/src/backend/access/brin/brin_xlog.c
@@ -180,11 +180,11 @@ brin_xlog_samepage_update(XLogReaderState *record)
 	if (action == BLK_NEEDS_REDO)
 	{
 		Size		tuplen;
-		BrinTuple  *mmtuple;
+		BrinTuple  *brintuple;
 		Page		page;
 		OffsetNumber offnum;
 
-		mmtuple = (BrinTuple *) XLogRecGetBlockData(record, 0, &tuplen);
+		brintuple = (BrinTuple *) XLogRecGetBlockData(record, 0, &tuplen);
 
 		page = (Page) BufferGetPage(buffer);
 
@@ -193,7 +193,7 @@ brin_xlog_samepage_update(XLogReaderState *record)
 			elog(PANIC, "brin_xlog_samepage_update: invalid max offset number");
 
 		PageIndexDeleteNoCompact(page, &offnum, 1);
-		offnum = PageAddItem(page, (Item) mmtuple, tuplen, offnum, true, false);
+		offnum = PageAddItem(page, (Item) brintuple, tuplen, offnum, true, false);
 		if (offnum == InvalidOffsetNumber)
 			elog(PANIC, "brin_xlog_samepage_update: failed to add tuple");