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 cdfe5dec565b85a8cd11bb7d9b7505d3d4c150d8..c8c3de72e335463aae0993cd7c25e94f7dd30c4e 100644 (file)
--- 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 ff18b220c2b8f9605a0ca07c1e9e82d5d95e9892..268a55e71f93a49451de2a392b3a8535f41f3415 100644 (file)
--- 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 09001552920b552e1dfb2f8b6020a041ab4efe19..760f0daf024df4fd14af409d4ea08d1193f8da12 100644 (file)
--- 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");