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 46a7d07bf8b670d77692a796ad1adb1db0c0e3bc..d7f1af7819a49a77aa1221b452654f993cd90f63 100644 (file)
--- a/doc/src/sgml/brin.sgml
+++ b/doc/src/sgml/brin.sgml
@@ -562,6 +562,36 @@ typedef struct BrinOpcInfo
    
   
 
+  Optionally, an operator class for BRIN can supply the
+  following method:
+
+  
+    
+     void options(local_relopts *relopts)
+     
+      
+       Defines set of user-visible parameters that control operator class
+       behavior.
+      
+
+      
+       The options function has given pointer to
+       local_relopts struct, which needs to be
+       filled with a set of operator class specific options.  The options
+       can be accessed from other support functions using
+       PG_HAS_OPCLASS_OPTIONS() and
+       PG_GET_OPCLASS_OPTIONS() macros.
+      
+
+      
+       Since both key extraction for indexed value and representation of the
+       key in GIN are flexible, it may depends on
+       user-specified parameters.
+      
+     
+    
+  
+
   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 73947db55cb44a41d3e201d1845c347c792dfc71..2c4dd48ea35f576e421067efd4260c3fa3c02e89 100644 (file)
--- a/doc/src/sgml/btree.sgml
+++ b/doc/src/sgml/btree.sgml
@@ -550,6 +550,39 @@ equalimage(opcintype oid) returns bool
     
    
   
+  
+   options
+   
+    
+     Optionally, a B-tree operator family may provide
+     options (operator class specific
+     options) support functions, registered under support
+     function number 5.  These functions define set of user-visible
+     parameters that control operator class behavior.
+    
+    
+     An options support function must have the
+     signature
+
+options(relopts local_relopts *) returns void
+
+     The function has given pointer to local_relopts
+     struct, which needs to be filled with a set of operator class
+     specific options.  The options can be accessed from other support
+     functions using PG_HAS_OPCLASS_OPTIONS() and
+     PG_GET_OPCLASS_OPTIONS() macros.
+    
+    
+     Currently, no B-Tree operator class has options
+     support function.  B-tree doesn't allow flexible representation of keys
+     like GiST, SP-GiST, GIN and BRIN do.  So, options
+     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 PostgreSQL.
+    
+   
+  
  
 
 

diff --git a/doc/src/sgml/gin.sgml b/doc/src/sgml/gin.sgml
index 0182b445855ca7d59ec57a4b07b9c781dfd9fb51..d85e7c8796bc39b1d5a8ce909da5afacd8b007fc 100644 (file)
--- a/doc/src/sgml/gin.sgml
+++ b/doc/src/sgml/gin.sgml
@@ -380,7 +380,7 @@
 
  
   Optionally, an operator class for GIN can supply the
-  following method:
+  following methods:
 
   
     
@@ -402,6 +402,30 @@
       
      
     
+    
+     void options(local_relopts *relopts)
+     
+      
+       Defines set of user-visible parameters that control operator class
+       behavior.
+      
+
+      
+       The options function has given pointer to
+       local_relopts struct, which needs to be
+       filled with s set of operator class specific options.  The options
+       can be accessed from other support functions using
+       PG_HAS_OPCLASS_OPTIONS() and
+       PG_GET_OPCLASS_OPTIONS() macros.
+      
+
+      
+       Since both key extraction for indexed value and representation of the
+       key in GIN are flexible, it may depends on
+       user-specified parameters.
+      
+     
+    
   
  
 

diff --git a/doc/src/sgml/gist.sgml b/doc/src/sgml/gist.sgml
index a7eec1e94970fc5baee92f0576480b3fa7cbe3a4..31c28fdb61c7bb77624322989efaf4463d9ef45e 100644 (file)
--- 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);
 
  
    There are five methods that an index operator class for
-   GiST must provide, and four that are optional.
+   GiST must provide, and five that are optional.
    Correctness of the index is ensured
    by proper implementation of the same, consistent
    and union 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 fetch is needed if the
    operator class wishes to support index-only scans, except when the
-   compress method is omitted.
+   compress method is omitted. The optional tenth method
+   options is needed if the operator class provides
+   the user-specified parameters.
  
 
  
@@ -939,6 +941,161 @@ my_fetch(PG_FUNCTION_ARGS)
 
      
     
+
+    
+     options
+     
+      
+       Allows defintion of user-visible parameters that control operator
+       class behavior.
+      
+
+      
+        The SQL declaration of the function must look like this:
+
+
+CREATE OR REPLACE FUNCTION my_options(internal)
+RETURNS void
+AS 'MODULE_PATHNAME'
+LANGUAGE C STRICT;
+
+      
+
+      
+       The function has given pointer to local_relopts
+       struct, which needs to be filled with a set of operator class
+       specific options.  The options can be accessed from other support
+       functions using PG_HAS_OPCLASS_OPTIONS() and
+       PG_GET_OPCLASS_OPTIONS() macros.
+      
+
+       
+        The sample implementation of my_option() and parameters usage
+        in the another support function are given below:
+
+
+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 */
+}
+
+
+      
+
+      
+       Since the representation of the key in GiST is
+       flexible, it may depends on user-specified parameters.  For instace,
+       the length of key signature may be such parameter.  See
+       gtsvector_options() for example.
+      
+     
+    
   
 
   

diff --git a/doc/src/sgml/indexam.sgml b/doc/src/sgml/indexam.sgml
index 37f8d8760a380fac2277178e9acf53e76215a23e..af87f172a7cd06a69b25be96bbdb63ac68b8689e 100644 (file)
--- 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 0e04a0867932ecbb16cda8c3749ca76051736f40..03f914735bdb7f9961f09cbad4658c8d4ba96a48 100644 (file)
--- a/doc/src/sgml/spgist.sgml
+++ b/doc/src/sgml/spgist.sgml
@@ -858,7 +858,7 @@ typedef struct spgLeafConsistentOut
    
 
  
-  The optional user-defined method is:
+  The optional user-defined method are:
  
 
  
@@ -875,6 +875,39 @@ typedef struct spgLeafConsistentOut
       
      
     
+    
+     options
+     
+      
+       Defines set of user-visible parameters that control operator class
+       behavior.
+      
+
+      
+        The SQL declaration of the function must look like this:
+
+
+CREATE OR REPLACE FUNCTION my_options(internal)
+RETURNS void
+AS 'MODULE_PATHNAME'
+LANGUAGE C STRICT;
+
+      
+
+      
+       The function has given pointer to local_relopts
+       struct, which needs to be filled with a set of operator class
+       specific options.  The options can be accessed from other support
+       functions using PG_HAS_OPCLASS_OPTIONS() and
+       PG_GET_OPCLASS_OPTIONS() macros.
+      
+
+      
+       Since the representation of the key in SP-GiST is
+       flexible, it may depends on user-specified parameters.
+      
+     
+    
   
 
   

diff --git a/doc/src/sgml/xindex.sgml b/doc/src/sgml/xindex.sgml
index 14c1701c9b572b3cabfb320167f0fbfb1c94736d..0e4587a81b98dc372fde841b41693de5cae9b047 100644 (file)
--- a/doc/src/sgml/xindex.sgml
+++ b/doc/src/sgml/xindex.sgml
@@ -409,6 +409,13 @@
    .
   
 
+  
+   Additionally, some opclasses allow user to set specific parameters, which
+   controls its behavior.  Each builtin index access method have optional
+   options support function, which defines set of
+   opclass-specific parameters.
+  
+
    
     B-Tree Support Functions
     
@@ -450,6 +457,13 @@
        
        4
       
+      
+       
+        Defines set of options that are specific for this operator class
+        (optional)
+       
+       5
+      
      
     
    
@@ -485,6 +499,13 @@
        
        2
       
+      
+       
+        Defines set of options that are specific for this operator class
+        (optional)
+       
+       3
+      
      
     
    
@@ -560,6 +581,14 @@
        index-only scans (optional)
        9
       
+      
+       options
+       
+        Defines set of options that are specific for this operator class
+        (optional)
+       
+       10
+      
      
     
    
@@ -611,6 +640,14 @@
         query qualifier
        5
       
+      
+       options
+       
+        Defines set of options that are specific for this operator class
+        (optional)
+       
+       6
+      
      
     
    
@@ -680,6 +717,14 @@
        
        6
       
+      
+       options
+       
+        Defines set of options that are specific for this operator class
+        (optional)
+       
+       7
+      
      
     
    
@@ -730,6 +775,14 @@
        
        4
       
+      
+       options
+       
+        Defines set of options that are specific for this operator class
+        (optional)
+       
+       5
+