pg.ddx.io pgsql-hackers@postgresql.org mailing list archive
help / color / mirror / Atom feedOperator class parameters and sgml docs
13+ messages / 4 participants
[nested] [flat]
* Operator class parameters and sgml docs
@ 2020-05-20 21:36 Peter Geoghegan <pg@bowt.ie>
0 siblings, 1 reply; 13+ messages in thread
From: Peter Geoghegan @ 2020-05-20 21:36 UTC (permalink / raw)
To: Alexander Korotkov <a.korotkov@postgrespro.ru>; +Cc: pgsql-hackers
Commit 911e7020770 added a variety of new support routines to index
AMs. For example, it added a support function 5 to btree (see
BTOPTIONS_PROC), but didn't document this alongside the other support
functions in btree.sgml.
It looks like the new support functions are fundamentally different to
the existing ones in that they exist only as a way of supplying
parameters to other support functions. The idea was to preserve
compatibility with the old support function signatures. Even still, I
think that the new support functions should get some mention alongside
the older support functions.
I also wonder whether or not xindex.sgml needs to be updated to
account for opclass parameters.
--
Peter Geoghegan
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Operator class parameters and sgml docs
@ 2020-05-21 00:17 Alexander Korotkov <a.korotkov@postgrespro.ru>
parent: Peter Geoghegan <pg@bowt.ie>
0 siblings, 1 reply; 13+ messages in thread
From: Alexander Korotkov @ 2020-05-21 00:17 UTC (permalink / raw)
To: Peter Geoghegan <pg@bowt.ie>; +Cc: pgsql-hackers
Hi, Peter!
On Thu, May 21, 2020 at 12:37 AM Peter Geoghegan <pg@bowt.ie> wrote:
> Commit 911e7020770 added a variety of new support routines to index
> AMs. For example, it added a support function 5 to btree (see
> BTOPTIONS_PROC), but didn't document this alongside the other support
> functions in btree.sgml.
>
> It looks like the new support functions are fundamentally different to
> the existing ones in that they exist only as a way of supplying
> parameters to other support functions. The idea was to preserve
> compatibility with the old support function signatures. Even still, I
> think that the new support functions should get some mention alongside
> the older support functions.
>
> I also wonder whether or not xindex.sgml needs to be updated to
> account for opclass parameters.
Thank you for pointing. I'm going to take a look on this in next few days.
------
Alexander Korotkov
Postgres Professional: http://www.postgrespro.com
The Russian Postgres Company
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Operator class parameters and sgml docs
@ 2020-05-28 20:02 Alexander Korotkov <a.korotkov@postgrespro.ru>
parent: Alexander Korotkov <a.korotkov@postgrespro.ru>
0 siblings, 1 reply; 13+ messages in thread
From: Alexander Korotkov @ 2020-05-28 20:02 UTC (permalink / raw)
To: Peter Geoghegan <pg@bowt.ie>; +Cc: pgsql-hackers
On Thu, May 21, 2020 at 3:17 AM Alexander Korotkov
<a.korotkov@postgrespro.ru> wrote:
>
> On Thu, May 21, 2020 at 12:37 AM Peter Geoghegan <pg@bowt.ie> wrote:
> > Commit 911e7020770 added a variety of new support routines to index
> > AMs. For example, it added a support function 5 to btree (see
> > BTOPTIONS_PROC), but didn't document this alongside the other support
> > functions in btree.sgml.
> >
> > It looks like the new support functions are fundamentally different to
> > the existing ones in that they exist only as a way of supplying
> > parameters to other support functions. The idea was to preserve
> > compatibility with the old support function signatures. Even still, I
> > think that the new support functions should get some mention alongside
> > the older support functions.
> >
> > I also wonder whether or not xindex.sgml needs to be updated to
> > account for opclass parameters.
>
> Thank you for pointing. I'm going to take a look on this in next few days.
I'm sorry for the delay. I was very busy with various stuff. I'm
going to post docs patch next week.
------
Alexander Korotkov
Postgres Professional: http://www.postgrespro.com
The Russian Postgres Company
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Operator class parameters and sgml docs
@ 2020-06-16 11:24 Alexander Korotkov <a.korotkov@postgrespro.ru>
parent: Alexander Korotkov <a.korotkov@postgrespro.ru>
0 siblings, 1 reply; 13+ messages in thread
From: Alexander Korotkov @ 2020-06-16 11:24 UTC (permalink / raw)
To: Peter Geoghegan <pg@bowt.ie>; +Cc: pgsql-hackers
On Thu, May 28, 2020 at 11:02 PM Alexander Korotkov
<a.korotkov@postgrespro.ru> wrote:
>
> On Thu, May 21, 2020 at 3:17 AM Alexander Korotkov
> <a.korotkov@postgrespro.ru> wrote:
> >
> > On Thu, May 21, 2020 at 12:37 AM Peter Geoghegan <pg@bowt.ie> wrote:
> > > Commit 911e7020770 added a variety of new support routines to index
> > > AMs. For example, it added a support function 5 to btree (see
> > > BTOPTIONS_PROC), but didn't document this alongside the other support
> > > functions in btree.sgml.
> > >
> > > It looks like the new support functions are fundamentally different to
> > > the existing ones in that they exist only as a way of supplying
> > > parameters to other support functions. The idea was to preserve
> > > compatibility with the old support function signatures. Even still, I
> > > think that the new support functions should get some mention alongside
> > > the older support functions.
> > >
> > > I also wonder whether or not xindex.sgml needs to be updated to
> > > account for opclass parameters.
> >
> > Thank you for pointing. I'm going to take a look on this in next few days.
>
> I'm sorry for the delay. I was very busy with various stuff. I'm
> going to post docs patch next week.
Thank you for patience. The documentation patch is attached. I think
it requires review by native english speaker.
------
Alexander Korotkov
Postgres Professional: http://www.postgrespro.com
The Russian Postgres Company
Attachments:
[application/octet-stream] opclass_options_doc.patch (12.8K, ../../CAPpHfdukTDQqWRjqh58rfQ7Pa0G6-hag8Eiwkb4=f3srhSRDSw@mail.gmail.com/2-opclass_options_doc.patch)
download | inline diff:
commit add6e90ae3670b5178f8104b5e88c7622fac5f92
Author: Alexander Korotkov <akorotkov@postgresql.org>
Date: Tue Jun 16 14:21:57 2020 +0300
Add documentation for opclass options
Reported-by:
Bug:
Discussion:
Author:
Reviewed-by:
Tested-by:
Backpatch-through:
diff --git a/doc/src/sgml/brin.sgml b/doc/src/sgml/brin.sgml
index 46a7d07bf8b..1ffb367d3bb 100644
--- a/doc/src/sgml/brin.sgml
+++ b/doc/src/sgml/brin.sgml
@@ -562,6 +562,36 @@ typedef struct BrinOpcInfo
</varlistentry>
</variablelist>
+ Optionally, an operator class for <acronym>BRIN</acronym> can supply the
+ following method:
+
+ <variablelist>
+ <varlistentry>
+ <term><function>void options(local_relopts *relopts)</function></term>
+ <listitem>
+ <para>
+ Defines set of user-visible parameters that controls operator class
+ behavior.
+ </para>
+
+ <para>
+ The <function>options</function> function has given pointer to
+ <replaceable>local_relopts</replaceable> struct, which needs to be
+ filled with set of operator class specific option. The options
+ could be accessible from each support function using
+ <literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
+ <literal>PG_GET_OPCLASS_OPTIONS()</literal> macros.
+ </para>
+
+ <para>
+ Since both key extraction for indexed value and representation of the
+ key in <acronym>GIN</acronym> are flexible, it may depends on
+ user-specified parameters.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
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
diff --git a/doc/src/sgml/btree.sgml b/doc/src/sgml/btree.sgml
index e9cab4a55dc..8df39cbee2d 100644
--- a/doc/src/sgml/btree.sgml
+++ b/doc/src/sgml/btree.sgml
@@ -550,6 +550,39 @@ equalimage(<replaceable>opcintype</replaceable> <type>oid</type>) returns bool
</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><function>options</function></term>
+ <listitem>
+ <para>
+ Optionally, a B-tree operator family may provide
+ <function>options</function> (<quote>operator class specific
+ options</quote>) support functions, registered under support
+ function number 5. These functions define set of user-visible
+ parameters that controls operator class behavior.
+ </para>
+ <para>
+ An <function>options</function> support function must have the
+ signature
+<synopsis>
+options(<replaceable>relopts</replaceable> <type>local_relopts *</type>) returns void
+</synopsis>
+ The function has given pointer to <replaceable>local_relopts</replaceable>
+ struct, which needs to be filled with set of operator class
+ specific option. The options could be accessible from each support
+ function using <literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
+ <literal>PG_GET_OPCLASS_OPTIONS()</literal> macros.
+ </para>
+ <para>
+ Currently, no B-Tree operator class has <function>options</function>
+ support function. B-tree doesn't allow flexible representation of keys
+ like GiST, SP-GiST, GIN and BRIN do. So, <function>options</function>
+ probably doesn't have much usage in current shape of B-tree index
+ access method. Nevertheless, this support function was added to B-tree
+ for uniformity, and probably it will found its usage during further
+ evolution of B-tree in <productname>PostgreSQL</productname>.
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
</sect1>
diff --git a/doc/src/sgml/gin.sgml b/doc/src/sgml/gin.sgml
index b4f6abae122..d29ca166e30 100644
--- a/doc/src/sgml/gin.sgml
+++ b/doc/src/sgml/gin.sgml
@@ -380,7 +380,7 @@
<para>
Optionally, an operator class for <acronym>GIN</acronym> can supply the
- following method:
+ following methods:
<variablelist>
<varlistentry>
@@ -402,6 +402,30 @@
</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><function>void options(local_relopts *relopts)</function></term>
+ <listitem>
+ <para>
+ Defines set of user-visible parameters that controls operator class
+ behavior.
+ </para>
+
+ <para>
+ The <function>options</function> function has given pointer to
+ <replaceable>local_relopts</replaceable> struct, which needs to be
+ filled with set of operator class specific option. The options
+ could be accessible from each support function using
+ <literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
+ <literal>PG_GET_OPCLASS_OPTIONS()</literal> macros.
+ </para>
+
+ <para>
+ Since both key extraction for indexed value and representation of the
+ key in <acronym>GIN</acronym> are flexible, it may depends on
+ user-specified parameters.
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
</para>
diff --git a/doc/src/sgml/gist.sgml b/doc/src/sgml/gist.sgml
index 60d77411e03..bc1bda78409 100644
--- a/doc/src/sgml/gist.sgml
+++ b/doc/src/sgml/gist.sgml
@@ -269,7 +269,7 @@ CREATE INDEX ON my_table USING GIST (my_inet_column inet_ops);
<para>
There are five methods that an index operator class for
- <acronym>GiST</acronym> must provide, and four that are optional.
+ <acronym>GiST</acronym> must provide, and five that are optional.
Correctness of the index is ensured
by proper implementation of the <function>same</function>, <function>consistent</function>
and <function>union</function> methods, while efficiency (size and speed) of the
@@ -287,7 +287,9 @@ CREATE INDEX ON my_table USING GIST (my_inet_column inet_ops);
if the operator class wishes to support ordered scans (nearest-neighbor
searches). The optional ninth method <function>fetch</function> is needed if the
operator class wishes to support index-only scans, except when the
- <function>compress</function> method is omitted.
+ <function>compress</function> method is omitted. The optional tenth method
+ <function>options</function> is needed if the operator class provides
+ the user-specified parameters.
</para>
<variablelist>
@@ -939,6 +941,63 @@ my_fetch(PG_FUNCTION_ARGS)
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term><function>options</function></term>
+ <listitem>
+ <para>
+ Allows defintion of user-visible parameters that controls operator
+ class behavior.
+ </para>
+
+ <para>
+ The <acronym>SQL</acronym> declaration of the function must look like this:
+
+<programlisting>
+CREATE OR REPLACE FUNCTION my_options(internal)
+RETURNS void
+AS 'MODULE_PATHNAME'
+LANGUAGE C STRICT;
+</programlisting>
+ </para>
+
+ <para>
+ The function has given pointer to <replaceable>local_relopts</replaceable>
+ struct, which needs to be filled with set of operator class
+ specific option. The options could be accessible from each support
+ function using <literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
+ <literal>PG_GET_OPCLASS_OPTIONS()</literal> macros.
+ </para>
+
+ <para>
+ The matching code in the C module could then follow this skeleton:
+
+<programlisting>
+PG_FUNCTION_INFO_V1(my_options);
+
+Datum
+my_options(PG_FUNCTION_ARGS)
+{
+ local_relopts *relopts = (local_relopts *) PG_GETARG_POINTER(0);
+
+ init_local_reloptions(relopts, sizeof(MyOptionsStruct));
+ add_local_int_reloption(relopts, "my_param", "my parameter name",
+ MY_PARAM_DEFAULT, MY_PARAM_MIN, MY_PARAM_MAX,
+ offsetof(MyOptionsStruct, my_param));
+
+ PG_RETURN_VOID();
+}
+</programlisting>
+ </para>
+
+ <para>
+ Since the representation of the key in <acronym>GiST</acronym> is
+ flexible, it may depends on user-specified parameters. For instace,
+ the length of key signature may be such parameter. See
+ <literal>gtsvector_options()</literal> for example.
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
<para>
diff --git a/doc/src/sgml/indexam.sgml b/doc/src/sgml/indexam.sgml
index 37f8d8760a3..af87f172a7c 100644
--- a/doc/src/sgml/indexam.sgml
+++ b/doc/src/sgml/indexam.sgml
@@ -96,6 +96,8 @@ typedef struct IndexAmRoutine
uint16 amstrategies;
/* total number of support functions that this AM uses */
uint16 amsupport;
+ /* opclass options support function number or 0 */
+ uint16 amoptsprocnum;
/* does AM support ORDER BY indexed column's value? */
bool amcanorder;
/* does AM support ORDER BY result of an operator on indexed column? */
diff --git a/doc/src/sgml/spgist.sgml b/doc/src/sgml/spgist.sgml
index edf4a67e526..272d2b998e5 100644
--- a/doc/src/sgml/spgist.sgml
+++ b/doc/src/sgml/spgist.sgml
@@ -858,7 +858,7 @@ typedef struct spgLeafConsistentOut
</variablelist>
<para>
- The optional user-defined method is:
+ The optional user-defined method are:
</para>
<variablelist>
@@ -875,6 +875,39 @@ typedef struct spgLeafConsistentOut
</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><function>options</function></term>
+ <listitem>
+ <para>
+ Defines set of user-visible parameters that controls operator class
+ behavior.
+ </para>
+
+ <para>
+ The <acronym>SQL</acronym> declaration of the function must look like this:
+
+<programlisting>
+CREATE OR REPLACE FUNCTION my_options(internal)
+RETURNS void
+AS 'MODULE_PATHNAME'
+LANGUAGE C STRICT;
+</programlisting>
+ </para>
+
+ <para>
+ The function has given pointer to <replaceable>local_relopts</replaceable>
+ struct, which needs to be filled with set of operator class
+ specific option. The options could be accessible from each support
+ function using <literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
+ <literal>PG_GET_OPCLASS_OPTIONS()</literal> macros.
+ </para>
+
+ <para>
+ Since the representation of the key in <acronym>SP-GiST</acronym> is
+ flexible, it may depends on user-specified parameters.
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
<para>
diff --git a/doc/src/sgml/xindex.sgml b/doc/src/sgml/xindex.sgml
index 14c1701c9b5..0e4587a81b9 100644
--- a/doc/src/sgml/xindex.sgml
+++ b/doc/src/sgml/xindex.sgml
@@ -409,6 +409,13 @@
<xref linkend="btree-support-funcs"/>.
</para>
+ <para>
+ Additionally, some opclasses allow user to set specific parameters, which
+ controls its behavior. Each builtin index access method have optional
+ <function>options</function> support function, which defines set of
+ opclass-specific parameters.
+ </para>
+
<table tocentry="1" id="xindex-btree-support-table">
<title>B-Tree Support Functions</title>
<tgroup cols="2">
@@ -450,6 +457,13 @@
</entry>
<entry>4</entry>
</row>
+ <row>
+ <entry>
+ Defines set of options that are specific for this operator class
+ (optional)
+ </entry>
+ <entry>5</entry>
+ </row>
</tbody>
</tgroup>
</table>
@@ -485,6 +499,13 @@
</entry>
<entry>2</entry>
</row>
+ <row>
+ <entry>
+ Defines set of options that are specific for this operator class
+ (optional)
+ </entry>
+ <entry>3</entry>
+ </row>
</tbody>
</tgroup>
</table>
@@ -560,6 +581,14 @@
index-only scans (optional)</entry>
<entry>9</entry>
</row>
+ <row>
+ <entry><function>options</function></entry>
+ <entry>
+ Defines set of options that are specific for this operator class
+ (optional)
+ </entry>
+ <entry>10</entry>
+ </row>
</tbody>
</tgroup>
</table>
@@ -611,6 +640,14 @@
query qualifier</entry>
<entry>5</entry>
</row>
+ <row>
+ <entry><function>options</function></entry>
+ <entry>
+ Defines set of options that are specific for this operator class
+ (optional)
+ </entry>
+ <entry>6</entry>
+ </row>
</tbody>
</tgroup>
</table>
@@ -680,6 +717,14 @@
</entry>
<entry>6</entry>
</row>
+ <row>
+ <entry><function>options</function></entry>
+ <entry>
+ Defines set of options that are specific for this operator class
+ (optional)
+ </entry>
+ <entry>7</entry>
+ </row>
</tbody>
</tgroup>
</table>
@@ -730,6 +775,14 @@
</entry>
<entry>4</entry>
</row>
+ <row>
+ <entry><function>options</function></entry>
+ <entry>
+ Defines set of options that are specific for this operator class
+ (optional)
+ </entry>
+ <entry>5</entry>
+ </row>
</tbody>
</tgroup>
</table>
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Operator class parameters and sgml docs
@ 2020-06-16 23:50 Peter Geoghegan <pg@bowt.ie>
parent: Alexander Korotkov <a.korotkov@postgrespro.ru>
0 siblings, 1 reply; 13+ messages in thread
From: Peter Geoghegan @ 2020-06-16 23:50 UTC (permalink / raw)
To: Alexander Korotkov <a.korotkov@postgrespro.ru>; +Cc: pgsql-hackers
On Tue, Jun 16, 2020 at 4:24 AM Alexander Korotkov
<a.korotkov@postgrespro.ru> wrote:
> Thank you for patience. The documentation patch is attached. I think
> it requires review by native english speaker.
* "...paramaters that controls" should be "...paramaters that control".
* "with set of operator class specific option" should be "with a set
of operator class specific options".
* "The options could be accessible from each support function" should
be "The options can be accessed from other support functions"
(At least I think that that's what you meant)
It's very hard to write documentation like this, even for native
English speakers. I think that it's important to have something in
place, though. The GiST example helps a lot.
--
Peter Geoghegan
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Operator class parameters and sgml docs
@ 2020-06-17 11:00 Alexander Korotkov <a.korotkov@postgrespro.ru>
parent: Peter Geoghegan <pg@bowt.ie>
0 siblings, 1 reply; 13+ messages in thread
From: Alexander Korotkov @ 2020-06-17 11:00 UTC (permalink / raw)
To: Peter Geoghegan <pg@bowt.ie>; +Cc: pgsql-hackers
On Wed, Jun 17, 2020 at 2:50 AM Peter Geoghegan <pg@bowt.ie> wrote:
> On Tue, Jun 16, 2020 at 4:24 AM Alexander Korotkov
> <a.korotkov@postgrespro.ru> wrote:
> > Thank you for patience. The documentation patch is attached. I think
> > it requires review by native english speaker.
>
> * "...paramaters that controls" should be "...paramaters that control".
>
> * "with set of operator class specific option" should be "with a set
> of operator class specific options".
>
> * "The options could be accessible from each support function" should
> be "The options can be accessed from other support functions"
Fixed, thanks!
> It's very hard to write documentation like this, even for native
> English speakers. I think that it's important to have something in
> place, though. The GiST example helps a lot.
I've added a complete example for defining a set of parameters and
accessing them from another support function to the GiST
documentation.
------
Alexander Korotkov
Postgres Professional: http://www.postgrespro.com
The Russian Postgres Company
Attachments:
[application/octet-stream] opclass_options_doc_2.patch (16.2K, ../../CAPpHfdv3bBjnOq6q2h_-eceHt6wiKasVgO2HSO14mkKPU+M42w@mail.gmail.com/2-opclass_options_doc_2.patch)
download | inline diff:
commit 24f61524d18336bdca7693402fd7c4a5d9cf0560
Author: Alexander Korotkov <akorotkov@postgresql.org>
Date: Tue Jun 16 14:21:57 2020 +0300
Add documentation for opclass options
911e7020770 added opclass options and adjusted documentation for each
particular affected opclass. However, documentation for extendability was
not adjusted. This commit adjusts documentation for interfaces of index AMs
and opclasses.
Discussion: https://postgr.es/m/CAH2-WzmQnW6%2Bz5F9AW%2BSz%2BzEcEvXofTwh_A9J3%3D_WA-FBP0wYg%40mail.gmail.com
Author: Alexander Korotkov
Reported-by: Peter Geoghegan
Reviewed-by: Peter Geoghegan
diff --git a/doc/src/sgml/brin.sgml b/doc/src/sgml/brin.sgml
index 46a7d07bf8b..d7f1af7819a 100644
--- a/doc/src/sgml/brin.sgml
+++ b/doc/src/sgml/brin.sgml
@@ -562,6 +562,36 @@ typedef struct BrinOpcInfo
</varlistentry>
</variablelist>
+ Optionally, an operator class for <acronym>BRIN</acronym> can supply the
+ following method:
+
+ <variablelist>
+ <varlistentry>
+ <term><function>void options(local_relopts *relopts)</function></term>
+ <listitem>
+ <para>
+ Defines set of user-visible parameters that control operator class
+ behavior.
+ </para>
+
+ <para>
+ The <function>options</function> function has given pointer to
+ <replaceable>local_relopts</replaceable> struct, which needs to be
+ filled with a set of operator class specific options. The options
+ can be accessed from other support functions using
+ <literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
+ <literal>PG_GET_OPCLASS_OPTIONS()</literal> macros.
+ </para>
+
+ <para>
+ Since both key extraction for indexed value and representation of the
+ key in <acronym>GIN</acronym> are flexible, it may depends on
+ user-specified parameters.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
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
diff --git a/doc/src/sgml/btree.sgml b/doc/src/sgml/btree.sgml
index e9cab4a55dc..f04ad9e1f89 100644
--- a/doc/src/sgml/btree.sgml
+++ b/doc/src/sgml/btree.sgml
@@ -550,6 +550,39 @@ equalimage(<replaceable>opcintype</replaceable> <type>oid</type>) returns bool
</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><function>options</function></term>
+ <listitem>
+ <para>
+ Optionally, a B-tree operator family may provide
+ <function>options</function> (<quote>operator class specific
+ options</quote>) support functions, registered under support
+ function number 5. These functions define set of user-visible
+ parameters that control operator class behavior.
+ </para>
+ <para>
+ An <function>options</function> support function must have the
+ signature
+<synopsis>
+options(<replaceable>relopts</replaceable> <type>local_relopts *</type>) returns void
+</synopsis>
+ The function has given pointer to <replaceable>local_relopts</replaceable>
+ struct, which needs to be filled with a set of operator class
+ specific options. The options can be accessed from other support
+ functions using <literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
+ <literal>PG_GET_OPCLASS_OPTIONS()</literal> macros.
+ </para>
+ <para>
+ Currently, no B-Tree operator class has <function>options</function>
+ support function. B-tree doesn't allow flexible representation of keys
+ like GiST, SP-GiST, GIN and BRIN do. So, <function>options</function>
+ probably doesn't have much usage in current shape of B-tree index
+ access method. Nevertheless, this support function was added to B-tree
+ for uniformity, and probably it will found its usage during further
+ evolution of B-tree in <productname>PostgreSQL</productname>.
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
</sect1>
diff --git a/doc/src/sgml/gin.sgml b/doc/src/sgml/gin.sgml
index b4f6abae122..15ae936a39f 100644
--- a/doc/src/sgml/gin.sgml
+++ b/doc/src/sgml/gin.sgml
@@ -380,7 +380,7 @@
<para>
Optionally, an operator class for <acronym>GIN</acronym> can supply the
- following method:
+ following methods:
<variablelist>
<varlistentry>
@@ -402,6 +402,30 @@
</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><function>void options(local_relopts *relopts)</function></term>
+ <listitem>
+ <para>
+ Defines set of user-visible parameters that control operator class
+ behavior.
+ </para>
+
+ <para>
+ The <function>options</function> function has given pointer to
+ <replaceable>local_relopts</replaceable> struct, which needs to be
+ filled with s set of operator class specific options. The options
+ can be accessed from other support functions using
+ <literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
+ <literal>PG_GET_OPCLASS_OPTIONS()</literal> macros.
+ </para>
+
+ <para>
+ Since both key extraction for indexed value and representation of the
+ key in <acronym>GIN</acronym> are flexible, it may depends on
+ user-specified parameters.
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
</para>
diff --git a/doc/src/sgml/gist.sgml b/doc/src/sgml/gist.sgml
index 60d77411e03..101e1463a68 100644
--- a/doc/src/sgml/gist.sgml
+++ b/doc/src/sgml/gist.sgml
@@ -269,7 +269,7 @@ CREATE INDEX ON my_table USING GIST (my_inet_column inet_ops);
<para>
There are five methods that an index operator class for
- <acronym>GiST</acronym> must provide, and four that are optional.
+ <acronym>GiST</acronym> must provide, and five that are optional.
Correctness of the index is ensured
by proper implementation of the <function>same</function>, <function>consistent</function>
and <function>union</function> methods, while efficiency (size and speed) of the
@@ -287,7 +287,9 @@ CREATE INDEX ON my_table USING GIST (my_inet_column inet_ops);
if the operator class wishes to support ordered scans (nearest-neighbor
searches). The optional ninth method <function>fetch</function> is needed if the
operator class wishes to support index-only scans, except when the
- <function>compress</function> method is omitted.
+ <function>compress</function> method is omitted. The optional tenth method
+ <function>options</function> is needed if the operator class provides
+ the user-specified parameters.
</para>
<variablelist>
@@ -939,6 +941,161 @@ my_fetch(PG_FUNCTION_ARGS)
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term><function>options</function></term>
+ <listitem>
+ <para>
+ Allows defintion of user-visible parameters that control operator
+ class behavior.
+ </para>
+
+ <para>
+ The <acronym>SQL</acronym> declaration of the function must look like this:
+
+<programlisting>
+CREATE OR REPLACE FUNCTION my_options(internal)
+RETURNS void
+AS 'MODULE_PATHNAME'
+LANGUAGE C STRICT;
+</programlisting>
+ </para>
+
+ <para>
+ The function has given pointer to <replaceable>local_relopts</replaceable>
+ struct, which needs to be filled with a set of operator class
+ specific options. The options can be accessed from other support
+ functions using <literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
+ <literal>PG_GET_OPCLASS_OPTIONS()</literal> macros.
+ </para>
+
+ <para>
+ The sample implementation of my_option() and parameters usage
+ in the another support function are given below:
+
+<programlisting>
+typedef enum MyEnumType
+{
+ MY_ENUM_ON,
+ MY_ENUM_OFF,
+ MY_ENUM_AUTO
+} MyEnumType;
+
+typedef struct
+{
+ int32 vl_len_; /* varlena header (do not touch directly!) */
+ int int_param; /* integer parameter */
+ double real_param; /* real parameter */
+ MyEnumType enum_param; /* enum parameter */
+ int str_param; /* string parameter */
+} MyOptionsStruct;
+
+/* String representations for enum values */
+static relopt_enum_elt_def myEnumValues[] =
+{
+ {"on", MY_ENUM_ON},
+ {"off", MY_ENUM_OFF},
+ {"auto", MY_ENUM_AUTO},
+ {(const char *) NULL} /* list terminator */
+};
+
+static char *str_param_default = "default";
+
+/*
+ * Sample validatior: checks that string is not longer than 8 bytes.
+ */
+static void
+validate_my_string_relopt(const char *value)
+{
+ if (strlen(value) > 8)
+ ereport(ERROR,
+ (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
+ errmsg("str_param must be at most 8 bytes")));
+}
+
+/*
+ * Sample filler: switches characters to lower case.
+ */
+static Size
+fill_my_string_relopt(const char *value, void *ptr)
+{
+ char *tmp = str_tolower(value, strlen(value), DEFAULT_COLLATION_OID);
+ int len = strlen(tmp);
+
+ if (ptr)
+ strcpy((char *) ptr, tmp);
+
+ pfree(tmp);
+ return len + 1;
+}
+
+PG_FUNCTION_INFO_V1(my_options);
+
+Datum
+my_options(PG_FUNCTION_ARGS)
+{
+ local_relopts *relopts = (local_relopts *) PG_GETARG_POINTER(0);
+
+ init_local_reloptions(relopts, sizeof(MyOptionsStruct));
+ add_local_int_reloption(relopts, "int_param", "integer parameter",
+ 100, 0, 1000000,
+ offsetof(MyOptionsStruct, int_param));
+ add_local_real_reloption(relopts, "real_param", "real parameter",
+ 1.0, 0.0, 1000000.0,
+ offsetof(MyOptionsStruct, real_param));
+ add_local_enum_reloption(relopts, "enum_param", "enum parameter",
+ myEnumValues, MY_ENUM_ON,
+ "Valid values are: \"on\", \"off\" and \"auto\".",
+ offsetof(MyOptionsStruct, enum_param));
+ add_local_string_reloption(relopts, "str_param", "string parameter",
+ str_param_default,
+ &validate_my_string_relopt,
+ &fill_my_string_relopt,
+ offsetof(MyOptionsStruct, str_param));
+
+ PG_RETURN_VOID();
+}
+
+PG_FUNCTION_INFO_V1(my_compress);
+
+Datum
+my_compress(PG_FUNCTION_ARGS)
+{
+ int int_param = 100;
+ double real_param = 1.0;
+ MyEnumType enum_param = MY_ENUM_ON;
+ char *str_param = str_param_default;
+
+ /*
+ * Normally, when opclass contains 'options' method, then options are always
+ * passed to support functions. However, if you add 'options' method to
+ * existing opclass, previously defined indexes have no options, so the
+ * check is required.
+ */
+ if (PG_HAS_OPCLASS_OPTIONS())
+ {
+ MyOptionsStruct *options = (MyOptionsStruct *) PG_GET_OPCLASS_OPTIONS();
+
+ int_param = options->int_param;
+ real_param = options->real_param;
+ enum_param = options->enum_param;
+ str_param = GET_STRING_RELOPTION(options, str_param);
+ }
+
+ /* the rest implementation of support function */
+}
+
+</programlisting>
+ </para>
+
+ <para>
+ Since the representation of the key in <acronym>GiST</acronym> is
+ flexible, it may depends on user-specified parameters. For instace,
+ the length of key signature may be such parameter. See
+ <literal>gtsvector_options()</literal> for example.
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
<para>
diff --git a/doc/src/sgml/indexam.sgml b/doc/src/sgml/indexam.sgml
index 37f8d8760a3..af87f172a7c 100644
--- a/doc/src/sgml/indexam.sgml
+++ b/doc/src/sgml/indexam.sgml
@@ -96,6 +96,8 @@ typedef struct IndexAmRoutine
uint16 amstrategies;
/* total number of support functions that this AM uses */
uint16 amsupport;
+ /* opclass options support function number or 0 */
+ uint16 amoptsprocnum;
/* does AM support ORDER BY indexed column's value? */
bool amcanorder;
/* does AM support ORDER BY result of an operator on indexed column? */
diff --git a/doc/src/sgml/spgist.sgml b/doc/src/sgml/spgist.sgml
index edf4a67e526..90734fff907 100644
--- a/doc/src/sgml/spgist.sgml
+++ b/doc/src/sgml/spgist.sgml
@@ -858,7 +858,7 @@ typedef struct spgLeafConsistentOut
</variablelist>
<para>
- The optional user-defined method is:
+ The optional user-defined method are:
</para>
<variablelist>
@@ -875,6 +875,39 @@ typedef struct spgLeafConsistentOut
</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><function>options</function></term>
+ <listitem>
+ <para>
+ Defines set of user-visible parameters that control operator class
+ behavior.
+ </para>
+
+ <para>
+ The <acronym>SQL</acronym> declaration of the function must look like this:
+
+<programlisting>
+CREATE OR REPLACE FUNCTION my_options(internal)
+RETURNS void
+AS 'MODULE_PATHNAME'
+LANGUAGE C STRICT;
+</programlisting>
+ </para>
+
+ <para>
+ The function has given pointer to <replaceable>local_relopts</replaceable>
+ struct, which needs to be filled with a set of operator class
+ specific options. The options can be accessed from other support
+ functions using <literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
+ <literal>PG_GET_OPCLASS_OPTIONS()</literal> macros.
+ </para>
+
+ <para>
+ Since the representation of the key in <acronym>SP-GiST</acronym> is
+ flexible, it may depends on user-specified parameters.
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
<para>
diff --git a/doc/src/sgml/xindex.sgml b/doc/src/sgml/xindex.sgml
index 14c1701c9b5..0e4587a81b9 100644
--- a/doc/src/sgml/xindex.sgml
+++ b/doc/src/sgml/xindex.sgml
@@ -409,6 +409,13 @@
<xref linkend="btree-support-funcs"/>.
</para>
+ <para>
+ Additionally, some opclasses allow user to set specific parameters, which
+ controls its behavior. Each builtin index access method have optional
+ <function>options</function> support function, which defines set of
+ opclass-specific parameters.
+ </para>
+
<table tocentry="1" id="xindex-btree-support-table">
<title>B-Tree Support Functions</title>
<tgroup cols="2">
@@ -450,6 +457,13 @@
</entry>
<entry>4</entry>
</row>
+ <row>
+ <entry>
+ Defines set of options that are specific for this operator class
+ (optional)
+ </entry>
+ <entry>5</entry>
+ </row>
</tbody>
</tgroup>
</table>
@@ -485,6 +499,13 @@
</entry>
<entry>2</entry>
</row>
+ <row>
+ <entry>
+ Defines set of options that are specific for this operator class
+ (optional)
+ </entry>
+ <entry>3</entry>
+ </row>
</tbody>
</tgroup>
</table>
@@ -560,6 +581,14 @@
index-only scans (optional)</entry>
<entry>9</entry>
</row>
+ <row>
+ <entry><function>options</function></entry>
+ <entry>
+ Defines set of options that are specific for this operator class
+ (optional)
+ </entry>
+ <entry>10</entry>
+ </row>
</tbody>
</tgroup>
</table>
@@ -611,6 +640,14 @@
query qualifier</entry>
<entry>5</entry>
</row>
+ <row>
+ <entry><function>options</function></entry>
+ <entry>
+ Defines set of options that are specific for this operator class
+ (optional)
+ </entry>
+ <entry>6</entry>
+ </row>
</tbody>
</tgroup>
</table>
@@ -680,6 +717,14 @@
</entry>
<entry>6</entry>
</row>
+ <row>
+ <entry><function>options</function></entry>
+ <entry>
+ Defines set of options that are specific for this operator class
+ (optional)
+ </entry>
+ <entry>7</entry>
+ </row>
</tbody>
</tgroup>
</table>
@@ -730,6 +775,14 @@
</entry>
<entry>4</entry>
</row>
+ <row>
+ <entry><function>options</function></entry>
+ <entry>
+ Defines set of options that are specific for this operator class
+ (optional)
+ </entry>
+ <entry>5</entry>
+ </row>
</tbody>
</tgroup>
</table>
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Operator class parameters and sgml docs
@ 2020-06-18 17:06 Alexander Korotkov <a.korotkov@postgrespro.ru>
parent: Alexander Korotkov <a.korotkov@postgrespro.ru>
0 siblings, 1 reply; 13+ messages in thread
From: Alexander Korotkov @ 2020-06-18 17:06 UTC (permalink / raw)
To: Peter Geoghegan <pg@bowt.ie>; +Cc: pgsql-hackers
On Wed, Jun 17, 2020 at 2:00 PM Alexander Korotkov
<a.korotkov@postgrespro.ru> wrote:
> On Wed, Jun 17, 2020 at 2:50 AM Peter Geoghegan <pg@bowt.ie> wrote:
> > On Tue, Jun 16, 2020 at 4:24 AM Alexander Korotkov
> > <a.korotkov@postgrespro.ru> wrote:
> > > Thank you for patience. The documentation patch is attached. I think
> > > it requires review by native english speaker.
> >
> > * "...paramaters that controls" should be "...paramaters that control".
> >
> > * "with set of operator class specific option" should be "with a set
> > of operator class specific options".
> >
> > * "The options could be accessible from each support function" should
> > be "The options can be accessed from other support functions"
>
> Fixed, thanks!
>
> > It's very hard to write documentation like this, even for native
> > English speakers. I think that it's important to have something in
> > place, though. The GiST example helps a lot.
>
> I've added a complete example for defining a set of parameters and
> accessing them from another support function to the GiST
> documentation.
I'm going to push this patch if there are no objections. I'm almost
sure that documentation of opclass options will require further
adjustments. However, I think the current patch makes it better, not
worse.
------
Alexander Korotkov
Postgres Professional: http://www.postgrespro.com
The Russian Postgres Company
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Operator class parameters and sgml docs
@ 2020-06-20 10:55 Alexander Korotkov <aekorotkov@gmail.com>
parent: Alexander Korotkov <a.korotkov@postgrespro.ru>
0 siblings, 2 replies; 13+ messages in thread
From: Alexander Korotkov @ 2020-06-20 10:55 UTC (permalink / raw)
To: Peter Geoghegan <pg@bowt.ie>; +Cc: pgsql-hackers
On Thu, Jun 18, 2020 at 8:06 PM Alexander Korotkov
<a.korotkov@postgrespro.ru> wrote:
> On Wed, Jun 17, 2020 at 2:00 PM Alexander Korotkov
> <a.korotkov@postgrespro.ru> wrote:
> > On Wed, Jun 17, 2020 at 2:50 AM Peter Geoghegan <pg@bowt.ie> wrote:
> > > On Tue, Jun 16, 2020 at 4:24 AM Alexander Korotkov
> > > <a.korotkov@postgrespro.ru> wrote:
> > > > Thank you for patience. The documentation patch is attached. I think
> > > > it requires review by native english speaker.
> > >
> > > * "...paramaters that controls" should be "...paramaters that control".
> > >
> > > * "with set of operator class specific option" should be "with a set
> > > of operator class specific options".
> > >
> > > * "The options could be accessible from each support function" should
> > > be "The options can be accessed from other support functions"
> >
> > Fixed, thanks!
> >
> > > It's very hard to write documentation like this, even for native
> > > English speakers. I think that it's important to have something in
> > > place, though. The GiST example helps a lot.
> >
> > I've added a complete example for defining a set of parameters and
> > accessing them from another support function to the GiST
> > documentation.
>
> I'm going to push this patch if there are no objections. I'm almost
> sure that documentation of opclass options will require further
> adjustments. However, I think the current patch makes it better, not
> worse.
So, pushed!
------
Regards,
Alexander Korotkov
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Operator class parameters and sgml docs
@ 2020-06-20 19:15 Peter Geoghegan <pg@bowt.ie>
parent: Alexander Korotkov <aekorotkov@gmail.com>
1 sibling, 1 reply; 13+ messages in thread
From: Peter Geoghegan @ 2020-06-20 19:15 UTC (permalink / raw)
To: Alexander Korotkov <aekorotkov@gmail.com>; +Cc: pgsql-hackers
On Sat, Jun 20, 2020 at 3:55 AM Alexander Korotkov <aekorotkov@gmail.com> wrote:
> So, pushed!
Noticed one small thing. You forgot to update this part from the B-Tree docs:
"As shown in Table 37.9, btree defines one required and three optional
support functions. The four user-defined methods are:"
Thanks
--
Peter Geoghegan
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Operator class parameters and sgml docs
@ 2020-06-20 21:39 Alexander Korotkov <aekorotkov@gmail.com>
parent: Peter Geoghegan <pg@bowt.ie>
0 siblings, 0 replies; 13+ messages in thread
From: Alexander Korotkov @ 2020-06-20 21:39 UTC (permalink / raw)
To: Peter Geoghegan <pg@bowt.ie>; +Cc: pgsql-hackers
On Sat, Jun 20, 2020 at 10:15 PM Peter Geoghegan <pg@bowt.ie> wrote:
> On Sat, Jun 20, 2020 at 3:55 AM Alexander Korotkov <aekorotkov@gmail.com> wrote:
> > So, pushed!
>
> Noticed one small thing. You forgot to update this part from the B-Tree docs:
>
> "As shown in Table 37.9, btree defines one required and three optional
> support functions. The four user-defined methods are:"
Thanks! I've also spotted a similar issue in SP-GiST. Fix for both is pushed.
------
Regards,
Alexander Korotkov
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Operator class parameters and sgml docs
@ 2020-06-20 23:21 Justin Pryzby <pryzby@telsasoft.com>
parent: Alexander Korotkov <aekorotkov@gmail.com>
1 sibling, 1 reply; 13+ messages in thread
From: Justin Pryzby @ 2020-06-20 23:21 UTC (permalink / raw)
To: Alexander Korotkov <aekorotkov@gmail.com>; +Cc: Peter Geoghegan <pg@bowt.ie>; pgsql-hackers
On Sat, Jun 20, 2020 at 01:55:33PM +0300, Alexander Korotkov wrote:
> On Thu, Jun 18, 2020 at 8:06 PM Alexander Korotkov <a.korotkov@postgrespro.ru> wrote:
> > On Wed, Jun 17, 2020 at 2:00 PM Alexander Korotkov <a.korotkov@postgrespro.ru> wrote:
> > > On Wed, Jun 17, 2020 at 2:50 AM Peter Geoghegan <pg@bowt.ie> wrote:
> > > > On Tue, Jun 16, 2020 at 4:24 AM Alexander Korotkov <a.korotkov@postgrespro.ru> wrote:
> > > > > Thank you for patience. The documentation patch is attached. I think
> > > > > it requires review by native english speaker.
...
> > > Fixed, thanks!
> > >
> > > > It's very hard to write documentation like this, even for native
> > > > English speakers. I think that it's important to have something in
> > > > place, though. The GiST example helps a lot.
...
> > I'm going to push this patch if there are no objections. I'm almost
> > sure that documentation of opclass options will require further
> > adjustments. However, I think the current patch makes it better, not
> > worse.
>
> So, pushed!
Find attached some language review of user-facing docs.
diff --git a/doc/src/sgml/brin.sgml b/doc/src/sgml/brin.sgml
index d7f1af7819..4c5eeb875f 100644
--- a/doc/src/sgml/brin.sgml
+++ b/doc/src/sgml/brin.sgml
@@ -562,7 +562,7 @@ typedef struct BrinOpcInfo
</varlistentry>
</variablelist>
[-Optionally, an-]{+An+} operator class for <acronym>BRIN</acronym> can [-supply-]{+optionally specify+} the
following method:
<variablelist>
@@ -570,22 +570,22 @@ typedef struct BrinOpcInfo
<term><function>void options(local_relopts *relopts)</function></term>
<listitem>
<para>
Defines {+a+} set of user-visible parameters that control operator class
behavior.
</para>
<para>
The <function>options</function> function [-has given-]{+is passed a+} pointer to {+a+}
<replaceable>local_relopts</replaceable> struct, which needs to be
filled with a set of operator class specific options. The options
can be accessed from other support functions using {+the+}
<literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
<literal>PG_GET_OPCLASS_OPTIONS()</literal> macros.
</para>
<para>
Since both key extraction [-for-]{+of+} indexed [-value-]{+values+} and representation of the
key in <acronym>GIN</acronym> are flexible, [-it-]{+they+} may [-depends-]{+depend+} on
user-specified parameters.
</para>
</listitem>
diff --git a/doc/src/sgml/btree.sgml b/doc/src/sgml/btree.sgml
index 2c4dd48ea3..b17b166e84 100644
--- a/doc/src/sgml/btree.sgml
+++ b/doc/src/sgml/btree.sgml
@@ -557,7 +557,7 @@ equalimage(<replaceable>opcintype</replaceable> <type>oid</type>) returns bool
Optionally, a B-tree operator family may provide
<function>options</function> (<quote>operator class specific
options</quote>) support functions, registered under support
function number 5. These functions define {+a+} set of user-visible
parameters that control operator class behavior.
</para>
<para>
@@ -566,19 +566,19 @@ equalimage(<replaceable>opcintype</replaceable> <type>oid</type>) returns bool
<synopsis>
options(<replaceable>relopts</replaceable> <type>local_relopts *</type>) returns void
</synopsis>
The function [-has given-]{+is passed a+} pointer to {+a+} <replaceable>local_relopts</replaceable>
struct, which needs to be filled with a set of operator class
specific options. The options can be accessed from other support
functions using {+the+} <literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
<literal>PG_GET_OPCLASS_OPTIONS()</literal> macros.
</para>
<para>
Currently, no B-Tree operator class has {+an+} <function>options</function>
support function. B-tree doesn't allow flexible representation of keys
like GiST, SP-GiST, GIN and BRIN do. So, <function>options</function>
probably doesn't have much [-usage-]{+application+} in {+the+} current[-shape of-] B-tree index
access method. Nevertheless, this support function was added to B-tree
for uniformity, and[-probably it-] will [-found its usage-]{+probably find uses+} during further
evolution of B-tree in <productname>PostgreSQL</productname>.
</para>
</listitem>
diff --git a/doc/src/sgml/gin.sgml b/doc/src/sgml/gin.sgml
index d85e7c8796..7a8c18a449 100644
--- a/doc/src/sgml/gin.sgml
+++ b/doc/src/sgml/gin.sgml
@@ -411,17 +411,17 @@
</para>
<para>
The <function>options</function> function [-has given-]{+is passed a+} pointer to {+a+}
<replaceable>local_relopts</replaceable> struct, which needs to be
filled with [-s-]{+a+} set of operator class specific options. The options
can be accessed from other support functions using {+the+}
<literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
<literal>PG_GET_OPCLASS_OPTIONS()</literal> macros.
</para>
<para>
Since both key extraction [-for-]{+of+} indexed [-value-]{+values+} and representation of the
key in <acronym>GIN</acronym> are flexible, [-it-]{+they+} may [-depends-]{+depend+} on
user-specified parameters.
</para>
</listitem>
diff --git a/doc/src/sgml/gist.sgml b/doc/src/sgml/gist.sgml
index 31c28fdb61..5d970ee9f2 100644
--- a/doc/src/sgml/gist.sgml
+++ b/doc/src/sgml/gist.sgml
@@ -946,7 +946,7 @@ my_fetch(PG_FUNCTION_ARGS)
<term><function>options</function></term>
<listitem>
<para>
Allows [-defintion-]{+definition+} of user-visible parameters that control operator
class behavior.
</para>
@@ -962,16 +962,16 @@ LANGUAGE C STRICT;
</para>
<para>
The function [-has given-]{+is passed a+} pointer to {+a+} <replaceable>local_relopts</replaceable>
struct, which needs to be filled with a set of operator class
specific options. The options can be accessed from other support
functions using {+the+} <literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
<literal>PG_GET_OPCLASS_OPTIONS()</literal> macros.
</para>
<para>
[-The sample-]{+An example+} implementation of [-my_option()-]{+my_options()+} and parameters [-usage-]
[- in the another-]{+use+}
{+ from other+} support [-function-]{+functions+} are given below:
<programlisting>
typedef enum MyEnumType
@@ -990,7 +990,7 @@ typedef struct
int str_param; /* string parameter */
} MyOptionsStruct;
/* String [-representations for-]{+representation of+} enum values */
static relopt_enum_elt_def myEnumValues[] =
{
{"on", MY_ENUM_ON},
@@ -1002,7 +1002,7 @@ static relopt_enum_elt_def myEnumValues[] =
static char *str_param_default = "default";
/*
* Sample [-validatior:-]{+validator:+} checks that string is not longer than 8 bytes.
*/
static void
validate_my_string_relopt(const char *value)
@@ -1090,8 +1090,8 @@ my_compress(PG_FUNCTION_ARGS)
<para>
Since the representation of the key in <acronym>GiST</acronym> is
flexible, it may [-depends-]{+depend+} on user-specified parameters. For [-instace,-]{+instance,+}
the length of key signature may be [-such parameter.-]{+specified.+} See
<literal>gtsvector_options()</literal> for example.
</para>
</listitem>
diff --git a/doc/src/sgml/spgist.sgml b/doc/src/sgml/spgist.sgml
index 03f914735b..1395dbaf88 100644
--- a/doc/src/sgml/spgist.sgml
+++ b/doc/src/sgml/spgist.sgml
@@ -895,16 +895,16 @@ LANGUAGE C STRICT;
</para>
<para>
The function [-has given-]{+is passed a+} pointer to {+a+} <replaceable>local_relopts</replaceable>
struct, which needs to be filled with a set of operator class
specific options. The options can be accessed from other support
functions using {+the+} <literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
<literal>PG_GET_OPCLASS_OPTIONS()</literal> macros.
</para>
<para>
Since the representation of the key in <acronym>SP-GiST</acronym> is
flexible, it may [-depends-]{+depend+} on user-specified parameters.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/xindex.sgml b/doc/src/sgml/xindex.sgml
index 0e4587a81b..2cfd71b5b7 100644
--- a/doc/src/sgml/xindex.sgml
+++ b/doc/src/sgml/xindex.sgml
@@ -410,9 +410,9 @@
</para>
<para>
Additionally, some opclasses allow [-user-]{+users+} to [-set specific parameters,-]{+specify parameters+} which
[-controls its-]{+control their+} behavior. Each builtin index access method [-have-]{+has an+} optional
<function>options</function> support function, which defines {+a+} set of
opclass-specific parameters.
</para>
@@ -459,7 +459,7 @@
</row>
<row>
<entry>
Defines {+a+} set of options that are specific [-for-]{+to+} this operator class
(optional)
</entry>
<entry>5</entry>
@@ -501,7 +501,7 @@
</row>
<row>
<entry>
Defines {+a+} set of options that are specific [-for-]{+to+} this operator class
(optional)
</entry>
<entry>3</entry>
@@ -584,7 +584,7 @@
<row>
<entry><function>options</function></entry>
<entry>
Defines {+a+} set of options that are specific [-for-]{+to+} this operator class
(optional)
</entry>
<entry>10</entry>
@@ -643,7 +643,7 @@
<row>
<entry><function>options</function></entry>
<entry>
Defines {+a+} set of options that are specific [-for-]{+to+} this operator class
(optional)
</entry>
<entry>6</entry>
@@ -720,7 +720,7 @@
<row>
<entry><function>options</function></entry>
<entry>
Defines {+a+} set of options that are specific [-for-]{+to+} this operator class
(optional)
</entry>
<entry>7</entry>
@@ -778,7 +778,7 @@
<row>
<entry><function>options</function></entry>
<entry>
Defines {+a+} set of options that are specific [-for-]{+to+} this operator class
(optional)
</entry>
<entry>5</entry>
Attachments:
[text/x-diff] v1-0001-Language-fixen-for-15cb2bd27009f73a84a35c2ba60fdd.patch (11.4K, ../../20200620232145.GB17995@telsasoft.com/2-v1-0001-Language-fixen-for-15cb2bd27009f73a84a35c2ba60fdd.patch)
download | inline diff:
From c590277f8ae3f77be420f93aeaece5cefdfd15a1 Mon Sep 17 00:00:00 2001
From: Justin Pryzby <pryzbyj@telsasoft.com>
Date: Sat, 20 Jun 2020 16:37:51 -0500
Subject: [PATCH v1] Language fixen for
15cb2bd27009f73a84a35c2ba60fdd105b4bf263
---
doc/src/sgml/brin.sgml | 12 ++++++------
doc/src/sgml/btree.sgml | 12 ++++++------
doc/src/sgml/gin.sgml | 10 +++++-----
doc/src/sgml/gist.sgml | 18 +++++++++---------
doc/src/sgml/spgist.sgml | 6 +++---
doc/src/sgml/xindex.sgml | 18 +++++++++---------
6 files changed, 38 insertions(+), 38 deletions(-)
diff --git a/doc/src/sgml/brin.sgml b/doc/src/sgml/brin.sgml
index d7f1af7819..4c5eeb875f 100644
--- a/doc/src/sgml/brin.sgml
+++ b/doc/src/sgml/brin.sgml
@@ -562,7 +562,7 @@ typedef struct BrinOpcInfo
</varlistentry>
</variablelist>
- Optionally, an operator class for <acronym>BRIN</acronym> can supply the
+ An operator class for <acronym>BRIN</acronym> can optionally specify the
following method:
<variablelist>
@@ -570,22 +570,22 @@ typedef struct BrinOpcInfo
<term><function>void options(local_relopts *relopts)</function></term>
<listitem>
<para>
- Defines set of user-visible parameters that control operator class
+ Defines a set of user-visible parameters that control operator class
behavior.
</para>
<para>
- The <function>options</function> function has given pointer to
+ The <function>options</function> function is passed a pointer to a
<replaceable>local_relopts</replaceable> struct, which needs to be
filled with a set of operator class specific options. The options
- can be accessed from other support functions using
+ can be accessed from other support functions using the
<literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
<literal>PG_GET_OPCLASS_OPTIONS()</literal> macros.
</para>
<para>
- Since both key extraction for indexed value and representation of the
- key in <acronym>GIN</acronym> are flexible, it may depends on
+ Since both key extraction of indexed values and representation of the
+ key in <acronym>GIN</acronym> are flexible, they may depend on
user-specified parameters.
</para>
</listitem>
diff --git a/doc/src/sgml/btree.sgml b/doc/src/sgml/btree.sgml
index 2c4dd48ea3..b17b166e84 100644
--- a/doc/src/sgml/btree.sgml
+++ b/doc/src/sgml/btree.sgml
@@ -557,7 +557,7 @@ equalimage(<replaceable>opcintype</replaceable> <type>oid</type>) returns bool
Optionally, a B-tree operator family may provide
<function>options</function> (<quote>operator class specific
options</quote>) support functions, registered under support
- function number 5. These functions define set of user-visible
+ function number 5. These functions define a set of user-visible
parameters that control operator class behavior.
</para>
<para>
@@ -566,19 +566,19 @@ equalimage(<replaceable>opcintype</replaceable> <type>oid</type>) returns bool
<synopsis>
options(<replaceable>relopts</replaceable> <type>local_relopts *</type>) returns void
</synopsis>
- The function has given pointer to <replaceable>local_relopts</replaceable>
+ The function is passed a pointer to a <replaceable>local_relopts</replaceable>
struct, which needs to be filled with a set of operator class
specific options. The options can be accessed from other support
- functions using <literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
+ functions using the <literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
<literal>PG_GET_OPCLASS_OPTIONS()</literal> macros.
</para>
<para>
- Currently, no B-Tree operator class has <function>options</function>
+ Currently, no B-Tree operator class has an <function>options</function>
support function. B-tree doesn't allow flexible representation of keys
like GiST, SP-GiST, GIN and BRIN do. So, <function>options</function>
- probably doesn't have much usage in current shape of B-tree index
+ probably doesn't have much application in the current B-tree index
access method. Nevertheless, this support function was added to B-tree
- for uniformity, and probably it will found its usage during further
+ for uniformity, and will probably find uses during further
evolution of B-tree in <productname>PostgreSQL</productname>.
</para>
</listitem>
diff --git a/doc/src/sgml/gin.sgml b/doc/src/sgml/gin.sgml
index d85e7c8796..7a8c18a449 100644
--- a/doc/src/sgml/gin.sgml
+++ b/doc/src/sgml/gin.sgml
@@ -411,17 +411,17 @@
</para>
<para>
- The <function>options</function> function has given pointer to
+ The <function>options</function> function is passed a pointer to a
<replaceable>local_relopts</replaceable> struct, which needs to be
- filled with s set of operator class specific options. The options
- can be accessed from other support functions using
+ filled with a set of operator class specific options. The options
+ can be accessed from other support functions using the
<literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
<literal>PG_GET_OPCLASS_OPTIONS()</literal> macros.
</para>
<para>
- Since both key extraction for indexed value and representation of the
- key in <acronym>GIN</acronym> are flexible, it may depends on
+ Since both key extraction of indexed values and representation of the
+ key in <acronym>GIN</acronym> are flexible, they may depend on
user-specified parameters.
</para>
</listitem>
diff --git a/doc/src/sgml/gist.sgml b/doc/src/sgml/gist.sgml
index 31c28fdb61..5d970ee9f2 100644
--- a/doc/src/sgml/gist.sgml
+++ b/doc/src/sgml/gist.sgml
@@ -946,7 +946,7 @@ my_fetch(PG_FUNCTION_ARGS)
<term><function>options</function></term>
<listitem>
<para>
- Allows defintion of user-visible parameters that control operator
+ Allows definition of user-visible parameters that control operator
class behavior.
</para>
@@ -962,16 +962,16 @@ LANGUAGE C STRICT;
</para>
<para>
- The function has given pointer to <replaceable>local_relopts</replaceable>
+ The function is passed a pointer to a <replaceable>local_relopts</replaceable>
struct, which needs to be filled with a set of operator class
specific options. The options can be accessed from other support
- functions using <literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
+ functions using the <literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
<literal>PG_GET_OPCLASS_OPTIONS()</literal> macros.
</para>
<para>
- The sample implementation of my_option() and parameters usage
- in the another support function are given below:
+ An example implementation of my_options() and parameters use
+ from other support functions are given below:
<programlisting>
typedef enum MyEnumType
@@ -990,7 +990,7 @@ typedef struct
int str_param; /* string parameter */
} MyOptionsStruct;
-/* String representations for enum values */
+/* String representation of enum values */
static relopt_enum_elt_def myEnumValues[] =
{
{"on", MY_ENUM_ON},
@@ -1002,7 +1002,7 @@ static relopt_enum_elt_def myEnumValues[] =
static char *str_param_default = "default";
/*
- * Sample validatior: checks that string is not longer than 8 bytes.
+ * Sample validator: checks that string is not longer than 8 bytes.
*/
static void
validate_my_string_relopt(const char *value)
@@ -1090,8 +1090,8 @@ my_compress(PG_FUNCTION_ARGS)
<para>
Since the representation of the key in <acronym>GiST</acronym> is
- flexible, it may depends on user-specified parameters. For instace,
- the length of key signature may be such parameter. See
+ flexible, it may depend on user-specified parameters. For instance,
+ the length of key signature may be specified. See
<literal>gtsvector_options()</literal> for example.
</para>
</listitem>
diff --git a/doc/src/sgml/spgist.sgml b/doc/src/sgml/spgist.sgml
index 03f914735b..1395dbaf88 100644
--- a/doc/src/sgml/spgist.sgml
+++ b/doc/src/sgml/spgist.sgml
@@ -895,16 +895,16 @@ LANGUAGE C STRICT;
</para>
<para>
- The function has given pointer to <replaceable>local_relopts</replaceable>
+ The function is passed a pointer to a <replaceable>local_relopts</replaceable>
struct, which needs to be filled with a set of operator class
specific options. The options can be accessed from other support
- functions using <literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
+ functions using the <literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
<literal>PG_GET_OPCLASS_OPTIONS()</literal> macros.
</para>
<para>
Since the representation of the key in <acronym>SP-GiST</acronym> is
- flexible, it may depends on user-specified parameters.
+ flexible, it may depend on user-specified parameters.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/xindex.sgml b/doc/src/sgml/xindex.sgml
index 0e4587a81b..2cfd71b5b7 100644
--- a/doc/src/sgml/xindex.sgml
+++ b/doc/src/sgml/xindex.sgml
@@ -410,9 +410,9 @@
</para>
<para>
- Additionally, some opclasses allow user to set specific parameters, which
- controls its behavior. Each builtin index access method have optional
- <function>options</function> support function, which defines set of
+ Additionally, some opclasses allow users to specify parameters which
+ control their behavior. Each builtin index access method has an optional
+ <function>options</function> support function, which defines a set of
opclass-specific parameters.
</para>
@@ -459,7 +459,7 @@
</row>
<row>
<entry>
- Defines set of options that are specific for this operator class
+ Defines a set of options that are specific to this operator class
(optional)
</entry>
<entry>5</entry>
@@ -501,7 +501,7 @@
</row>
<row>
<entry>
- Defines set of options that are specific for this operator class
+ Defines a set of options that are specific to this operator class
(optional)
</entry>
<entry>3</entry>
@@ -584,7 +584,7 @@
<row>
<entry><function>options</function></entry>
<entry>
- Defines set of options that are specific for this operator class
+ Defines a set of options that are specific to this operator class
(optional)
</entry>
<entry>10</entry>
@@ -643,7 +643,7 @@
<row>
<entry><function>options</function></entry>
<entry>
- Defines set of options that are specific for this operator class
+ Defines a set of options that are specific to this operator class
(optional)
</entry>
<entry>6</entry>
@@ -720,7 +720,7 @@
<row>
<entry><function>options</function></entry>
<entry>
- Defines set of options that are specific for this operator class
+ Defines a set of options that are specific to this operator class
(optional)
</entry>
<entry>7</entry>
@@ -778,7 +778,7 @@
<row>
<entry><function>options</function></entry>
<entry>
- Defines set of options that are specific for this operator class
+ Defines a set of options that are specific to this operator class
(optional)
</entry>
<entry>5</entry>
--
2.17.0
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Operator class parameters and sgml docs
@ 2020-06-20 23:28 Justin Pryzby <pryzby@telsasoft.com>
parent: Justin Pryzby <pryzby@telsasoft.com>
0 siblings, 1 reply; 13+ messages in thread
From: Justin Pryzby @ 2020-06-20 23:28 UTC (permalink / raw)
To: Alexander Korotkov <aekorotkov@gmail.com>; +Cc: Peter Geoghegan <pg@bowt.ie>; pgsql-hackers
And a couple more in spgist.sgml (some of which were not added by this patch).
Attachments:
[text/x-diff] v2-0001-Language-fixen-for-15cb2bd27009f73a84a35c2ba60fdd.patch (12.6K, ../../20200620232816.GA23670@telsasoft.com/2-v2-0001-Language-fixen-for-15cb2bd27009f73a84a35c2ba60fdd.patch)
download | inline diff:
From ed7bd93c6a6953d8626331de9bcba126ddb79b54 Mon Sep 17 00:00:00 2001
From: Justin Pryzby <pryzbyj@telsasoft.com>
Date: Sat, 20 Jun 2020 16:37:51 -0500
Subject: [PATCH v2] Language fixen for
15cb2bd27009f73a84a35c2ba60fdd105b4bf263
---
doc/src/sgml/brin.sgml | 12 ++++++------
doc/src/sgml/btree.sgml | 12 ++++++------
doc/src/sgml/gin.sgml | 10 +++++-----
doc/src/sgml/gist.sgml | 18 +++++++++---------
doc/src/sgml/spgist.sgml | 12 ++++++------
doc/src/sgml/xindex.sgml | 18 +++++++++---------
6 files changed, 41 insertions(+), 41 deletions(-)
diff --git a/doc/src/sgml/brin.sgml b/doc/src/sgml/brin.sgml
index d7f1af7819..4c5eeb875f 100644
--- a/doc/src/sgml/brin.sgml
+++ b/doc/src/sgml/brin.sgml
@@ -562,7 +562,7 @@ typedef struct BrinOpcInfo
</varlistentry>
</variablelist>
- Optionally, an operator class for <acronym>BRIN</acronym> can supply the
+ An operator class for <acronym>BRIN</acronym> can optionally specify the
following method:
<variablelist>
@@ -570,22 +570,22 @@ typedef struct BrinOpcInfo
<term><function>void options(local_relopts *relopts)</function></term>
<listitem>
<para>
- Defines set of user-visible parameters that control operator class
+ Defines a set of user-visible parameters that control operator class
behavior.
</para>
<para>
- The <function>options</function> function has given pointer to
+ The <function>options</function> function is passed a pointer to a
<replaceable>local_relopts</replaceable> struct, which needs to be
filled with a set of operator class specific options. The options
- can be accessed from other support functions using
+ can be accessed from other support functions using the
<literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
<literal>PG_GET_OPCLASS_OPTIONS()</literal> macros.
</para>
<para>
- Since both key extraction for indexed value and representation of the
- key in <acronym>GIN</acronym> are flexible, it may depends on
+ Since both key extraction of indexed values and representation of the
+ key in <acronym>GIN</acronym> are flexible, they may depend on
user-specified parameters.
</para>
</listitem>
diff --git a/doc/src/sgml/btree.sgml b/doc/src/sgml/btree.sgml
index 661e7ab650..6c2fd453f5 100644
--- a/doc/src/sgml/btree.sgml
+++ b/doc/src/sgml/btree.sgml
@@ -557,7 +557,7 @@ equalimage(<replaceable>opcintype</replaceable> <type>oid</type>) returns bool
Optionally, a B-tree operator family may provide
<function>options</function> (<quote>operator class specific
options</quote>) support functions, registered under support
- function number 5. These functions define set of user-visible
+ function number 5. These functions define a set of user-visible
parameters that control operator class behavior.
</para>
<para>
@@ -566,19 +566,19 @@ equalimage(<replaceable>opcintype</replaceable> <type>oid</type>) returns bool
<synopsis>
options(<replaceable>relopts</replaceable> <type>local_relopts *</type>) returns void
</synopsis>
- The function has given pointer to <replaceable>local_relopts</replaceable>
+ The function is passed a pointer to a <replaceable>local_relopts</replaceable>
struct, which needs to be filled with a set of operator class
specific options. The options can be accessed from other support
- functions using <literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
+ functions using the <literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
<literal>PG_GET_OPCLASS_OPTIONS()</literal> macros.
</para>
<para>
- Currently, no B-Tree operator class has <function>options</function>
+ Currently, no B-Tree operator class has an <function>options</function>
support function. B-tree doesn't allow flexible representation of keys
like GiST, SP-GiST, GIN and BRIN do. So, <function>options</function>
- probably doesn't have much usage in current shape of B-tree index
+ probably doesn't have much application in the current B-tree index
access method. Nevertheless, this support function was added to B-tree
- for uniformity, and probably it will found its usage during further
+ for uniformity, and will probably find uses during further
evolution of B-tree in <productname>PostgreSQL</productname>.
</para>
</listitem>
diff --git a/doc/src/sgml/gin.sgml b/doc/src/sgml/gin.sgml
index d85e7c8796..7a8c18a449 100644
--- a/doc/src/sgml/gin.sgml
+++ b/doc/src/sgml/gin.sgml
@@ -411,17 +411,17 @@
</para>
<para>
- The <function>options</function> function has given pointer to
+ The <function>options</function> function is passed a pointer to a
<replaceable>local_relopts</replaceable> struct, which needs to be
- filled with s set of operator class specific options. The options
- can be accessed from other support functions using
+ filled with a set of operator class specific options. The options
+ can be accessed from other support functions using the
<literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
<literal>PG_GET_OPCLASS_OPTIONS()</literal> macros.
</para>
<para>
- Since both key extraction for indexed value and representation of the
- key in <acronym>GIN</acronym> are flexible, it may depends on
+ Since both key extraction of indexed values and representation of the
+ key in <acronym>GIN</acronym> are flexible, they may depend on
user-specified parameters.
</para>
</listitem>
diff --git a/doc/src/sgml/gist.sgml b/doc/src/sgml/gist.sgml
index 31c28fdb61..5d970ee9f2 100644
--- a/doc/src/sgml/gist.sgml
+++ b/doc/src/sgml/gist.sgml
@@ -946,7 +946,7 @@ my_fetch(PG_FUNCTION_ARGS)
<term><function>options</function></term>
<listitem>
<para>
- Allows defintion of user-visible parameters that control operator
+ Allows definition of user-visible parameters that control operator
class behavior.
</para>
@@ -962,16 +962,16 @@ LANGUAGE C STRICT;
</para>
<para>
- The function has given pointer to <replaceable>local_relopts</replaceable>
+ The function is passed a pointer to a <replaceable>local_relopts</replaceable>
struct, which needs to be filled with a set of operator class
specific options. The options can be accessed from other support
- functions using <literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
+ functions using the <literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
<literal>PG_GET_OPCLASS_OPTIONS()</literal> macros.
</para>
<para>
- The sample implementation of my_option() and parameters usage
- in the another support function are given below:
+ An example implementation of my_options() and parameters use
+ from other support functions are given below:
<programlisting>
typedef enum MyEnumType
@@ -990,7 +990,7 @@ typedef struct
int str_param; /* string parameter */
} MyOptionsStruct;
-/* String representations for enum values */
+/* String representation of enum values */
static relopt_enum_elt_def myEnumValues[] =
{
{"on", MY_ENUM_ON},
@@ -1002,7 +1002,7 @@ static relopt_enum_elt_def myEnumValues[] =
static char *str_param_default = "default";
/*
- * Sample validatior: checks that string is not longer than 8 bytes.
+ * Sample validator: checks that string is not longer than 8 bytes.
*/
static void
validate_my_string_relopt(const char *value)
@@ -1090,8 +1090,8 @@ my_compress(PG_FUNCTION_ARGS)
<para>
Since the representation of the key in <acronym>GiST</acronym> is
- flexible, it may depends on user-specified parameters. For instace,
- the length of key signature may be such parameter. See
+ flexible, it may depend on user-specified parameters. For instance,
+ the length of key signature may be specified. See
<literal>gtsvector_options()</literal> for example.
</para>
</listitem>
diff --git a/doc/src/sgml/spgist.sgml b/doc/src/sgml/spgist.sgml
index ad8d348a43..d9ecfe74ed 100644
--- a/doc/src/sgml/spgist.sgml
+++ b/doc/src/sgml/spgist.sgml
@@ -290,13 +290,13 @@
values for the support method, while the second argument is a pointer to a
C struct where output values must be placed. Four of the mandatory methods just
return <type>void</type>, since all their results appear in the output struct; but
- <function>leaf_consistent</function> additionally returns a <type>boolean</type> result.
+ <function>leaf_consistent</function> returns a <type>boolean</type> result.
The methods must not modify any fields of their input structs. In all
cases, the output struct is initialized to zeroes before calling the
user-defined method. The optional sixth method <function>compress</function>
- accepts datum to be indexed as the only argument and returns a value suitable
+ accepts a <type>datum</type> to be indexed as the only argument and returns a value suitable
for physical storage in a leaf tuple. The optional seventh method
- <function>options</function> accepts internal pointer to a C struct, where
+ <function>options</function> accepts an <type>internal</type> pointer to a C struct, where
opclass-specific parameters should be placed, and returns <type>void</type>.
</para>
@@ -897,16 +897,16 @@ LANGUAGE C STRICT;
</para>
<para>
- The function has given pointer to <replaceable>local_relopts</replaceable>
+ The function is passed a pointer to a <replaceable>local_relopts</replaceable>
struct, which needs to be filled with a set of operator class
specific options. The options can be accessed from other support
- functions using <literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
+ functions using the <literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
<literal>PG_GET_OPCLASS_OPTIONS()</literal> macros.
</para>
<para>
Since the representation of the key in <acronym>SP-GiST</acronym> is
- flexible, it may depends on user-specified parameters.
+ flexible, it may depend on user-specified parameters.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/xindex.sgml b/doc/src/sgml/xindex.sgml
index 0e4587a81b..2cfd71b5b7 100644
--- a/doc/src/sgml/xindex.sgml
+++ b/doc/src/sgml/xindex.sgml
@@ -410,9 +410,9 @@
</para>
<para>
- Additionally, some opclasses allow user to set specific parameters, which
- controls its behavior. Each builtin index access method have optional
- <function>options</function> support function, which defines set of
+ Additionally, some opclasses allow users to specify parameters which
+ control their behavior. Each builtin index access method has an optional
+ <function>options</function> support function, which defines a set of
opclass-specific parameters.
</para>
@@ -459,7 +459,7 @@
</row>
<row>
<entry>
- Defines set of options that are specific for this operator class
+ Defines a set of options that are specific to this operator class
(optional)
</entry>
<entry>5</entry>
@@ -501,7 +501,7 @@
</row>
<row>
<entry>
- Defines set of options that are specific for this operator class
+ Defines a set of options that are specific to this operator class
(optional)
</entry>
<entry>3</entry>
@@ -584,7 +584,7 @@
<row>
<entry><function>options</function></entry>
<entry>
- Defines set of options that are specific for this operator class
+ Defines a set of options that are specific to this operator class
(optional)
</entry>
<entry>10</entry>
@@ -643,7 +643,7 @@
<row>
<entry><function>options</function></entry>
<entry>
- Defines set of options that are specific for this operator class
+ Defines a set of options that are specific to this operator class
(optional)
</entry>
<entry>6</entry>
@@ -720,7 +720,7 @@
<row>
<entry><function>options</function></entry>
<entry>
- Defines set of options that are specific for this operator class
+ Defines a set of options that are specific to this operator class
(optional)
</entry>
<entry>7</entry>
@@ -778,7 +778,7 @@
<row>
<entry><function>options</function></entry>
<entry>
- Defines set of options that are specific for this operator class
+ Defines a set of options that are specific to this operator class
(optional)
</entry>
<entry>5</entry>
--
2.17.0
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Operator class parameters and sgml docs
@ 2020-06-21 01:52 Alexander Korotkov <aekorotkov@gmail.com>
parent: Justin Pryzby <pryzby@telsasoft.com>
0 siblings, 0 replies; 13+ messages in thread
From: Alexander Korotkov @ 2020-06-21 01:52 UTC (permalink / raw)
To: Justin Pryzby <pryzby@telsasoft.com>; +Cc: Peter Geoghegan <pg@bowt.ie>; pgsql-hackers
On Sun, Jun 21, 2020 at 2:28 AM Justin Pryzby <pryzby@telsasoft.com> wrote:
> And a couple more in spgist.sgml (some of which were not added by this patch).
Pushed, thanks!
------
Regards,
Alexander Korotkov
^ permalink raw reply [nested|flat] 13+ messages in thread
end of thread, other threads:[~2020-06-21 01:52 UTC | newest]
Thread overview: 13+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2020-05-20 21:36 Operator class parameters and sgml docs Peter Geoghegan <pg@bowt.ie>
2020-05-21 00:17 ` Alexander Korotkov <a.korotkov@postgrespro.ru>
2020-05-28 20:02 ` Alexander Korotkov <a.korotkov@postgrespro.ru>
2020-06-16 11:24 ` Alexander Korotkov <a.korotkov@postgrespro.ru>
2020-06-16 23:50 ` Peter Geoghegan <pg@bowt.ie>
2020-06-17 11:00 ` Alexander Korotkov <a.korotkov@postgrespro.ru>
2020-06-18 17:06 ` Alexander Korotkov <a.korotkov@postgrespro.ru>
2020-06-20 10:55 ` Alexander Korotkov <aekorotkov@gmail.com>
2020-06-20 19:15 ` Peter Geoghegan <pg@bowt.ie>
2020-06-20 21:39 ` Alexander Korotkov <aekorotkov@gmail.com>
2020-06-20 23:21 ` Justin Pryzby <pryzby@telsasoft.com>
2020-06-20 23:28 ` Justin Pryzby <pryzby@telsasoft.com>
2020-06-21 01:52 ` Alexander Korotkov <aekorotkov@gmail.com>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox