Refactor all the 'H5VL_*_optional' callbacks to move the type of operation out

of the va_list, so it's at least possible for another connector to know what
the operation is and decide whether to implement it or not.

Added a new VOL sub-class called "introspect" where callbacks that report
information about the connector or container can be placed.  Added an
'opt_query' callback to this sub-class, for a connector to report back
to the library whether a particular optional callback operation is supported.
Also added a 'get_conn_cls' introspection callback, to retrieve the H5VL_class_t
of a connector (either the "current" connector, H5VL_GET_CONN_LVL_CURR, or
the terminal connector, H5VL_GET_CONN_LVL_TERM).

Moved the "post open" operation from a file 'specific' operation to a file
'optional' operation, now that it's possible to detect (with the 'opt_query'
introspection callback) whether a VOL connector implements an optional
operation, without just returning an error.

Added new internal VOL helper routines: H5VL_object_is_native, to determine
if an object is in (or is a) native file, and H5VL_file_is_same, to determine
if two objects are in (or are) the same terminal VOL connector's container.
(And moved the special handling for FILE_IS_EQUAL operation out of internal VOL
callback routine into H5VL_file_is_same)

Made new dataset 'get' operation for H5Dvlen_get_buf_size, aligning it better
with other 'get' operations in API.

Fixed several issues with pass-through connectors, which are now passing the
'make check-passthrough-vol' tests again.

A bunch of warning and style cleanups as well.

1 files changed, 85 insertions, 14 deletions

diff --git a/src/H5VLconnector.h b/src/H5VLconnector.h
index 373eb44..0d9f4a0 100644
--- a/src/H5VLconnector.h
+++ b/src/H5VLconnector.h
@@ -50,6 +50,23 @@
 /* Public Typedefs */
 /*******************/
 
+/* Enum type for each VOL subclass */
+/* (Used for various queries, etc) */
+typedef enum H5VL_subclass_t {
+    H5VL_SUBCLS_NONE,                   /* Operations outside of a subclass */
+    H5VL_SUBCLS_INFO,                   /* 'Info' subclass */
+    H5VL_SUBCLS_WRAP,                   /* 'Wrap' subclass */
+    H5VL_SUBCLS_ATTR,                   /* 'Attribute' subclass */
+    H5VL_SUBCLS_DATASET,                /* 'Dataset' subclass */
+    H5VL_SUBCLS_DATATYPE,               /* 'Named datatype' subclass */
+    H5VL_SUBCLS_FILE,                   /* 'File' subclass */
+    H5VL_SUBCLS_GROUP,                  /* 'Group' subclass */
+    H5VL_SUBCLS_LINK,                   /* 'Link' subclass */
+    H5VL_SUBCLS_OBJECT,                 /* 'Object' subclass */
+    H5VL_SUBCLS_REQUEST,                /* 'Request' subclass */
+    H5VL_SUBCLS_BLOB                    /* 'Blob' subclass */
+} H5VL_subclass_t;
+
 /* type for tokens. Token are unique and permanent identifiers that are
  * used to reference HDF5 objects. */
 typedef struct {
@@ -74,15 +91,19 @@ typedef enum H5VL_attr_specific_t {
     H5VL_ATTR_RENAME                        /* H5Arename(_by_name)                 */
 } H5VL_attr_specific_t;
 
+/* Typedef for VOL connector attribute optional VOL operations */
+typedef int H5VL_attr_optional_t;
+
 /* types for dataset GET callback */
 typedef enum H5VL_dataset_get_t {
     H5VL_DATASET_GET_DAPL,                  /* access property list                */
     H5VL_DATASET_GET_DCPL,                  /* creation property list              */
     H5VL_DATASET_GET_OFFSET,                /* offset                              */
     H5VL_DATASET_GET_SPACE,                 /* dataspace                           */
-    H5VL_DATASET_GET_SPACE_STATUS,          /* space  status                       */
+    H5VL_DATASET_GET_SPACE_STATUS,          /* space status                        */
     H5VL_DATASET_GET_STORAGE_SIZE,          /* storage size                        */
-    H5VL_DATASET_GET_TYPE                   /* datatype                            */
+    H5VL_DATASET_GET_TYPE,                  /* datatype                            */
+    H5VL_DATASET_GET_VLEN_BUF_SIZE          /* vlen buffer size                    */
 } H5VL_dataset_get_t;
 
 /* types for dataset SPECFIC callback */
@@ -92,6 +113,9 @@ typedef enum H5VL_dataset_specific_t {
     H5VL_DATASET_REFRESH                    /* H5Drefresh                          */
 } H5VL_dataset_specific_t;
 
+/* Typedef for VOL connector dataset optional VOL operations */
+typedef int H5VL_dataset_optional_t;
+
 /* types for datatype GET callback */
 typedef enum H5VL_datatype_get_t {
     H5VL_DATATYPE_GET_BINARY,               /* get serialized form of transient type    */
@@ -104,6 +128,10 @@ typedef enum H5VL_datatype_specific_t {
     H5VL_DATATYPE_REFRESH
 } H5VL_datatype_specific_t;
 
+/* Typedef and values for native VOL connector named datatype optional VOL operations */
+typedef int H5VL_datatype_optional_t;
+/* (No optional named datatype VOL operations currently) */
+
 /* types for file GET callback */
 typedef enum H5VL_file_get_t {
     H5VL_FILE_GET_CONT_INFO,                /* file get container info              */
@@ -118,7 +146,6 @@ typedef enum H5VL_file_get_t {
 
 /* types for file SPECIFIC callback */
 typedef enum H5VL_file_specific_t {
-    H5VL_FILE_POST_OPEN,                    /* Adjust file after open, with wrapping context */
     H5VL_FILE_FLUSH,                        /* Flush file                       */
     H5VL_FILE_REOPEN,                       /* Reopen the file                  */
     H5VL_FILE_MOUNT,                        /* Mount a file                     */
@@ -128,6 +155,9 @@ typedef enum H5VL_file_specific_t {
     H5VL_FILE_IS_EQUAL                      /* Check if two files are the same  */
 } H5VL_file_specific_t;
 
+/* Typedef for VOL connector file optional VOL operations */
+typedef int H5VL_file_optional_t;
+
 /* types for group GET callback */
 typedef enum H5VL_group_get_t {
     H5VL_GROUP_GET_GCPL,                    /* group creation property list     */
@@ -140,6 +170,9 @@ typedef enum H5VL_group_specific_t {
     H5VL_GROUP_REFRESH
 } H5VL_group_specific_t;
 
+/* Typedef for VOL connector group optional VOL operations */
+typedef int H5VL_group_optional_t;
+
 /* link create types for VOL */
 typedef enum H5VL_link_create_type_t {
     H5VL_LINK_CREATE_HARD,
@@ -161,6 +194,10 @@ typedef enum H5VL_link_specific_t {
     H5VL_LINK_ITER             /* H5Literate/visit(_by_name)              */
 } H5VL_link_specific_t;
 
+/* Typedef and values for native VOL connector link optional VOL operations */
+typedef int H5VL_link_optional_t;
+/* (No optional link VOL operations currently) */
+
 /* types for object GET callback */
 typedef enum H5VL_object_get_t {
     H5VL_OBJECT_GET_FILE,              /* object file                       */
@@ -178,6 +215,9 @@ typedef enum H5VL_object_specific_t {
     H5VL_OBJECT_REFRESH                 /* H5{D|G|O|T}refresh                */
 } H5VL_object_specific_t;
 
+/* Typedef for VOL connector object optional VOL operations */
+typedef int H5VL_object_optional_t;
+
 /* types for async request SPECIFIC callback */
 typedef enum H5VL_request_specific_t {
     H5VL_REQUEST_WAITANY,               /* Wait until any request completes */
@@ -185,6 +225,10 @@ typedef enum H5VL_request_specific_t {
     H5VL_REQUEST_WAITALL                /* Wait until all requests complete */
 } H5VL_request_specific_t;
 
+/* Typedef and values for native VOL connector request optional VOL operations */
+typedef int H5VL_request_optional_t;
+/* (No optional request VOL operations currently) */
+
 /* types for 'blob' SPECIFIC callback */
 typedef enum H5VL_blob_specific_t {
     H5VL_BLOB_DELETE,                   /* Delete a blob (by ID) */
@@ -193,6 +237,10 @@ typedef enum H5VL_blob_specific_t {
     H5VL_BLOB_SETNULL                   /* Set a blob ID to the connector's "null" blob ID value */
 } H5VL_blob_specific_t;
 
+/* Typedef and values for native VOL connector blob optional VOL operations */
+typedef int H5VL_blob_optional_t;
+/* (No optional blob VOL operations currently) */
+
 /* Types for different ways that objects are located in an HDF5 container */
 typedef enum H5VL_loc_type_t {
     H5VL_OBJECT_BY_SELF,
@@ -278,7 +326,8 @@ typedef struct H5VL_attr_class_t {
     herr_t (*get)(void *obj, H5VL_attr_get_t get_type, hid_t dxpl_id, void **req, va_list arguments);
     herr_t (*specific)(void *obj, const H5VL_loc_params_t *loc_params, H5VL_attr_specific_t specific_type,
                        hid_t dxpl_id, void **req, va_list arguments);
-    herr_t (*optional)(void *obj, hid_t dxpl_id, void **req, va_list arguments);
+    herr_t (*optional)(void *obj, H5VL_attr_optional_t opt_type, hid_t dxpl_id,
+        void **req, va_list arguments);
     herr_t (*close) (void *attr, hid_t dxpl_id, void **req);
 } H5VL_attr_class_t;
 
@@ -296,7 +345,8 @@ typedef struct H5VL_dataset_class_t {
     herr_t (*get)(void *obj, H5VL_dataset_get_t get_type, hid_t dxpl_id, void **req, va_list arguments);
     herr_t (*specific)(void *obj, H5VL_dataset_specific_t specific_type,
                        hid_t dxpl_id, void **req, va_list arguments);
-    herr_t (*optional)(void *obj, hid_t dxpl_id, void **req, va_list arguments);
+    herr_t (*optional)(void *obj, H5VL_dataset_optional_t opt_type, hid_t dxpl_id,
+        void **req, va_list arguments);
     herr_t (*close) (void *dset, hid_t dxpl_id, void **req);
 } H5VL_dataset_class_t;
 
@@ -309,7 +359,7 @@ typedef struct H5VL_datatype_class_t {
     herr_t (*get)   (void *obj, H5VL_datatype_get_t get_type, hid_t dxpl_id, void **req, va_list arguments);
     herr_t (*specific)(void *obj, H5VL_datatype_specific_t specific_type,
                        hid_t dxpl_id, void **req, va_list arguments);
-    herr_t (*optional)(void *obj, hid_t dxpl_id, void **req, va_list arguments);
+    herr_t (*optional)(void *obj, H5VL_datatype_optional_t opt_type, hid_t dxpl_id, void **req, va_list arguments);
     herr_t (*close) (void *dt, hid_t dxpl_id, void **req);
 } H5VL_datatype_class_t;
 
@@ -321,7 +371,8 @@ typedef struct H5VL_file_class_t {
     herr_t (*get)(void *obj, H5VL_file_get_t get_type, hid_t dxpl_id, void **req, va_list arguments);
     herr_t (*specific)(void *obj, H5VL_file_specific_t specific_type,
                        hid_t dxpl_id, void **req, va_list arguments);
-    herr_t (*optional)(void *obj, hid_t dxpl_id, void **req, va_list arguments);
+    herr_t (*optional)(void *obj, H5VL_file_optional_t opt_type, hid_t dxpl_id,
+                       void **req, va_list arguments);
     herr_t (*close) (void *file, hid_t dxpl_id, void **req);
 } H5VL_file_class_t;
 
@@ -334,7 +385,7 @@ typedef struct H5VL_group_class_t {
     herr_t (*get)(void *obj, H5VL_group_get_t get_type, hid_t dxpl_id, void **req, va_list arguments);
     herr_t (*specific)(void *obj, H5VL_group_specific_t specific_type,
                        hid_t dxpl_id, void **req, va_list arguments);
-    herr_t (*optional)(void *obj, hid_t dxpl_id, void **req, va_list arguments);
+    herr_t (*optional)(void *obj, H5VL_group_optional_t opt_type, hid_t dxpl_id, void **req, va_list arguments);
     herr_t (*close) (void *grp, hid_t dxpl_id, void **req);
 } H5VL_group_class_t;
 
@@ -352,7 +403,8 @@ typedef struct H5VL_link_class_t {
                   hid_t dxpl_id, void **req, va_list arguments);
     herr_t (*specific)(void *obj, const H5VL_loc_params_t *loc_params, H5VL_link_specific_t specific_type,
                        hid_t dxpl_id, void **req, va_list arguments);
-    herr_t (*optional)(void *obj, hid_t dxpl_id, void **req, va_list arguments);
+    herr_t (*optional)(void *obj, H5VL_link_optional_t opt_type, hid_t dxpl_id,
+                       void **req, va_list arguments);
 } H5VL_link_class_t;
 
 /* H5O routines */
@@ -366,19 +418,37 @@ typedef struct H5VL_object_class_t {
                   hid_t dxpl_id, void **req, va_list arguments);
     herr_t (*specific)(void *obj, const H5VL_loc_params_t *loc_params, H5VL_object_specific_t specific_type,
                        hid_t dxpl_id, void **req, va_list arguments);
-    herr_t (*optional)(void *obj, hid_t dxpl_id, void **req, va_list arguments);
+    herr_t (*optional)(void *obj, H5VL_object_optional_t opt_type,
+                       hid_t dxpl_id, void **req, va_list arguments);
 } H5VL_object_class_t;
 
 /* Asynchronous request 'notify' callback */
 typedef herr_t (*H5VL_request_notify_t)(void *ctx, H5ES_status_t status);
 
+/* "Levels" for 'get connector class' introspection callback */
+typedef enum H5VL_get_conn_lvl_t {
+    H5VL_GET_CONN_LVL_CURR,         /* Get "current" connector (for this object) */
+    H5VL_GET_CONN_LVL_TERM          /* Get "terminal" connector (for this object) */
+                                    /* (Recursively called, for pass-through connectors) */
+                                    /* (Connectors that "split" must choose which connector to return) */
+} H5VL_get_conn_lvl_t;
+
+/* Forward declaration of H5VL_class_t, defined later in this file */
+struct H5VL_class_t;
+
+/* Container/connector introspection routines */
+typedef struct H5VL_introspect_class_t {
+    herr_t (*get_conn_cls)(void *obj, H5VL_get_conn_lvl_t lvl, const struct H5VL_class_t **conn_cls);
+    herr_t (*opt_query)(void *obj, H5VL_subclass_t cls, int opt_type, hbool_t *supported);
+} H5VL_introspect_class_t;
+
 /* Async request operation routines */
 typedef struct H5VL_request_class_t {
     herr_t (*wait)(void *req, uint64_t timeout, H5ES_status_t *status);
     herr_t (*notify)(void *req, H5VL_request_notify_t cb, void *ctx);
     herr_t (*cancel)(void *req);
     herr_t (*specific)(void *req, H5VL_request_specific_t specific_type, va_list arguments);
-    herr_t (*optional)(void *req, va_list arguments);
+    herr_t (*optional)(void *req, H5VL_request_optional_t opt_type, va_list arguments);
     herr_t (*free)(void *req);
 } H5VL_request_class_t;
 
@@ -387,7 +457,7 @@ typedef struct H5VL_blob_class_t {
     herr_t (*put)(void *obj, const void *buf, size_t size, void *blob_id, void *ctx);
     herr_t (*get)(void *obj, const void *blob_id, void *buf, size_t size, void *ctx);
     herr_t (*specific)(void *obj, void *blob_id, H5VL_blob_specific_t specific_type, va_list arguments);
-    herr_t (*optional)(void *obj, void *blob_id, va_list arguments);
+    herr_t (*optional)(void *obj, void *blob_id, H5VL_blob_optional_t opt_type, va_list arguments);
 } H5VL_blob_class_t;
 
 /*
@@ -422,11 +492,12 @@ typedef struct H5VL_class_t {
     H5VL_object_class_t     object_cls;     /* Object (H5O*) class callbacks    */
 
     /* Infrastructure / Services */
+    H5VL_introspect_class_t introspect_cls; /* Container/connector introspection class callbacks */
     H5VL_request_class_t    request_cls;    /* Asynchronous request class callbacks */
-    H5VL_blob_class_t       blob_cls;       /* 'blob' callbacks */
+    H5VL_blob_class_t       blob_cls;       /* 'Blob' class callbacks */
 
     /* Catch-all */
-    herr_t (*optional)(void *obj, hid_t dxpl_id, void **req, va_list arguments); /* Optional callback */
+    herr_t (*optional)(void *obj, int op_type, hid_t dxpl_id, void **req, va_list arguments); /* Optional callback */
 } H5VL_class_t;