Brings over a bunch of develop boilerplate

6 files changed, 258 insertions, 35 deletions

diff --git a/src/H5ESpublic.h b/src/H5ESpublic.h
index 28b41fa..9cc800a 100644
--- a/src/H5ESpublic.h
+++ b/src/H5ESpublic.h
@@ -24,18 +24,93 @@
 /* Public Macros */
 /*****************/
 
+/* Default value for "no event set" / synchronous execution */
+#define H5ES_NONE (hid_t)0
+
+/* Special "wait" timeout values */
+#define H5ES_WAIT_FOREVER (UINT64_MAX) /* Wait until all operations complete */
+#define H5ES_WAIT_NONE                                                                                       \
+    (0) /* Don't wait for operations to complete,                                                            \
+         *  just check their status.                                                                         \
+         *  (this allows H5ESwait to behave                                                                  \
+         *   like a 'test' operation)                                                                        \
+         */
+
 /*******************/
 /* Public Typedefs */
 /*******************/
 
 /* Asynchronous operation status */
 typedef enum H5ES_status_t {
-    H5ES_STATUS_IN_PROGRESS, /* Operation has not yet completed                       */
-    H5ES_STATUS_SUCCEED,     /* Operation has completed, successfully                 */
-    H5ES_STATUS_FAIL,        /* Operation has completed, but failed                   */
-    H5ES_STATUS_CANCELED     /* Operation has not completed and was canceled          */
+    H5ES_STATUS_IN_PROGRESS, /* Operation(s) have not yet completed                       */
+    H5ES_STATUS_SUCCEED,     /* Operation(s) have completed, successfully                 */
+    H5ES_STATUS_FAIL         /* An operation has completed, but failed                   */
 } H5ES_status_t;
 
+//! <!-- [H5ES_err_info_t_snip] -->
+/**
+ * Information about failed operations in event set
+ */
+typedef struct H5ES_err_info_t {
+    /* Operation info */
+    char *   api_name;      /**< Name of HDF5 API routine called */
+    char *   api_args;      /**< "Argument string" for arguments to HDF5 API routine called */
+    char *   app_file_name; /**< Name of source file where the HDF5 API routine was called */
+    char *   app_func_name; /**< Name of function where the HDF5 API routine was called */
+    unsigned app_line_num;  /**< Line # of source file where the HDF5 API routine was called */
+    uint64_t op_ins_count;  /**< Counter of operation's insertion into event set */
+    uint64_t op_ins_ts;     /**< Timestamp for when the operation was inserted into the event set */
+
+    /* Error info */
+    hid_t err_stack_id; /**< ID for error stack from failed operation */
+} H5ES_err_info_t;
+//! <!-- [H5ES_err_info_t_snip] -->
+
+/*
+H5ES_op_info_t:
+    const char *: API name (H5Dwrite_async, ...)
+    const char *: Arg string
+    const char *: Appl. source file name
+    const char *: Appl. source function
+    unsigned: Appl. source file line
+    uint64_t: Insert Time Timestamp
+    uint64_t: "event count" - n'th event inserted into event set
+    uint64_t: Execution Time timestamp (*)
+
+More Possible Info for H5ES_op_info_t:
+    Parent Operation's request token (*) -> "parent event count"? -- Could be
+        used to "prune" child operations from reported errors, with flag
+        to H5ESget_err_info?
+
+H5ES_err_info_t:
+    H5ES_op_info_t: (above)
+    hid_t: Error stack (*)
+
+Possible debugging routines:  (Should also be configured from Env Var)
+    H5ESdebug_signal(hid_t es_id, signal_t sig, uint64_t <event count>);
+    H5ESdebug_err_trace_log(hid_t es_id, const char *filename);
+    H5ESdebug_err_trace_fh(hid_t es_id, FILE *fh);
+    H5ESdebug_err_signal(hid_t es_id, signal_t sig);
+[Possibly option to allow operations to be inserted into event set with error?]
+
+    Example usage:
+        es_id = H5EScreate();
+        H5ESdebug...(es_id, ...);
+        ...
+        H5Dwrite_async(..., es_id);
+
+How to Trace Async Operations?
+    <Example of stacking Logging VOL Connector w/Async VOL Connector>
+
+"Library / wrapper developer" version of API routines: (Auto-generated)
+    H5Dwrite_async_wrap(const char *app_file, const char *app_func,
+        unsigned app_line_num, dset_id, mem_type_id, mem_space_id, ..., es_id);
+
+    vs.
+
+    H5Dwrite_async(dset_id, mem_type_id, mem_space_id, ..., es_id);
+*/
+
 /********************/
 /* Public Variables */
 /********************/
diff --git a/src/H5VLconnector.h b/src/H5VLconnector.h
index dca2864..1bc6c40 100644
--- a/src/H5VLconnector.h
+++ b/src/H5VLconnector.h
@@ -81,7 +81,8 @@ typedef enum H5VL_dataset_get_t {
 typedef enum H5VL_dataset_specific_t {
     H5VL_DATASET_SET_EXTENT, /* H5Dset_extent                       */
     H5VL_DATASET_FLUSH,      /* H5Dflush                            */
-    H5VL_DATASET_REFRESH     /* H5Drefresh                          */
+    H5VL_DATASET_REFRESH,    /* H5Drefresh                          */
+    H5VL_DATASET_WAIT        /* H5Dwait                             */
 } H5VL_dataset_specific_t;
 
 /* Typedef for VOL connector dataset optional VOL operations */
@@ -120,7 +121,8 @@ typedef enum H5VL_file_specific_t {
     H5VL_FILE_UNMOUNT,       /* Unmount a file                   */
     H5VL_FILE_IS_ACCESSIBLE, /* Check if a file is accessible    */
     H5VL_FILE_DELETE,        /* Delete a file                    */
-    H5VL_FILE_IS_EQUAL       /* Check if two files are the same  */
+    H5VL_FILE_IS_EQUAL,      /* Check if two files are the same  */
+    H5VL_FILE_WAIT           /* Wait for async operations to complete */
 } H5VL_file_specific_t;
 
 /* Typedef for VOL connector file optional VOL operations */
@@ -184,11 +186,25 @@ typedef enum H5VL_object_specific_t {
 /* Typedef for VOL connector object optional VOL operations */
 typedef int H5VL_object_optional_t;
 
+/* Status values for async request operations */
+typedef enum H5VL_request_status_t {
+    H5VL_REQUEST_STATUS_IN_PROGRESS, /* Operation has not yet completed                       */
+    H5VL_REQUEST_STATUS_SUCCEED,     /* Operation has completed, successfully                 */
+    H5VL_REQUEST_STATUS_FAIL,        /* Operation has completed, but failed                   */
+    H5VL_REQUEST_STATUS_CANT_CANCEL, /* An attempt to cancel this operation was made, but it  */
+                                     /*  can't be canceled immediately.  The operation has    */
+                                     /*  not completed successfully or failed, and is not yet */
+                                     /*  in progress.  Another attempt to cancel it may be    */
+                                     /*  attempted and may (or may not) succeed.              */
+    H5VL_REQUEST_STATUS_CANCELED     /* Operation has not completed and was canceled          */
+} H5VL_request_status_t;
+
 /* types for async request SPECIFIC callback */
 typedef enum H5VL_request_specific_t {
-    H5VL_REQUEST_WAITANY,  /* Wait until any request completes */
-    H5VL_REQUEST_WAITSOME, /* Wait until at least one requesst completes */
-    H5VL_REQUEST_WAITALL   /* Wait until all requests complete */
+    H5VL_REQUEST_WAITANY,      /* Wait until any request completes */
+    H5VL_REQUEST_WAITSOME,     /* Wait until at least one requesst completes */
+    H5VL_REQUEST_WAITALL,      /* Wait until all requests complete */
+    H5VL_REQUEST_GET_ERR_STACK /* Retrieve error stack for failed operation */
 } H5VL_request_specific_t;
 
 /* Typedef and values for native VOL connector request optional VOL operations */
@@ -438,10 +454,14 @@ typedef struct H5VL_token_class_t {
     herr_t (*from_str)(void *obj, H5I_type_t obj_type, const char *token_str, H5O_token_t *token);
 } H5VL_token_class_t;
 
-/* Class information for each VOL connector */
+/**
+ * \ingroup H5VLDEV
+ * Class information for each VOL connector
+ */
+//! <!-- [H5VL_class_t_snip] -->
 typedef struct H5VL_class_t {
     /* Overall connector fields & callbacks */
-    unsigned int       version;          /* VOL connector class struct version #     */
+    unsigned           version;          /* VOL connector class struct version #     */
     H5VL_class_value_t value;            /* Value to identify connector              */
     const char *       name;             /* Connector name (MUST be unique!)         */
     unsigned           cap_flags;        /* Capability flags for connector           */
@@ -471,6 +491,7 @@ typedef struct H5VL_class_t {
     herr_t (*optional)(void *obj, int op_type, hid_t dxpl_id, void **req,
                        va_list arguments); /* Optional callback */
 } H5VL_class_t;
+//! <!-- [H5VL_class_t_snip] -->
 
 /********************/
 /* Public Variables */
diff --git a/src/H5VLpublic.h b/src/H5VLpublic.h
index 58a8045..d0076b1 100644
--- a/src/H5VLpublic.h
+++ b/src/H5VLpublic.h
@@ -25,42 +25,97 @@
 /* Public Macros */
 /*****************/
 
+/**
+ * \ingroup H5VLDEF
+ * \brief Version # of VOL class struct & callbacks
+ *
+ * \details Each VOL connector must set the 'version' field in the H5VL_class_t
+ *          struct to the version of the H5VL_class_t struct that the connector
+ *          implements.  The HDF5 library will reject connectors with
+ *          incompatible structs.
+ */
+#define H5VL_VERSION 2
+
 /* VOL connector identifier values
  * These are H5VL_class_value_t values, NOT hid_t values!
  */
-#define H5_VOL_INVALID  (-1)  /* Invalid ID for VOL connector ID */
-#define H5_VOL_NATIVE   0     /* Native HDF5 file format VOL connector */
-#define H5_VOL_RESERVED 256   /* VOL connector IDs below this value are reserved for library use */
-#define H5_VOL_MAX      65535 /* Maximum VOL connector ID */
+/**
+ * \ingroup H5VLDEF
+ * Invalid ID for VOL connector ID
+ */
+#define H5_VOL_INVALID (-1)
+/**
+ * \ingroup H5VLDEF
+ * Native HDF5 file format VOL connector
+ */
+#define H5_VOL_NATIVE 0
+/**
+ * \ingroup H5VLDEF
+ * VOL connector IDs below this value are reserved for library use
+ */
+#define H5_VOL_RESERVED 256
+/**
+ * \ingroup H5VLDEF
+ * Maximum VOL connector ID
+ */
+#define H5_VOL_MAX 65535
+
+/* Flags to return from H5VLquery_optional API and 'opt_query' callbacks */
+/* Note: Operations which access multiple objects' data or metadata in a
+ *      container should be registered as file-level optional operations.
+ *      (e.g. "H5Dwrite_multi" takes a list of datasets to write data to, so
+ *      a VOL connector that implemented it should register it as an optional
+ *      file operation, and pass-through VOL connectors that are stacked above
+ *      the connector that registered it should assume that dataset elements
+ *      for _any_ dataset in the file could be written to)
+ */
+#define H5VL_OPT_QUERY_SUPPORTED       0x0001 /* VOL connector supports this operation */
+#define H5VL_OPT_QUERY_READ_DATA       0x0002 /* Operation reads data for object */
+#define H5VL_OPT_QUERY_WRITE_DATA      0x0004 /* Operation writes data for object */
+#define H5VL_OPT_QUERY_QUERY_METADATA  0x0008 /* Operation reads metadata for object */
+#define H5VL_OPT_QUERY_MODIFY_METADATA 0x0010 /* Operation modifies metadata for object */
+#define H5VL_OPT_QUERY_COLLECTIVE                                                                            \
+    0x0020 /* Operation is collective (operations without this flag are assumed to be independent) */
+#define H5VL_OPT_QUERY_NO_ASYNC  0x0040 /* Operation may NOT be executed asynchronously */
+#define H5VL_OPT_QUERY_MULTI_OBJ 0x0080 /* Operation involves multiple objects */
 
 /*******************/
 /* Public Typedefs */
 /*******************/
 
-/*
- * VOL connector identifiers.  Values 0 through 255 are for connectors defined
- * by the HDF5 library.  Values 256 through 511 are available for testing new
- * connectors. Subsequent values should be obtained from the HDF5 development
- * team at help@hdfgroup.org.
+/**
+ * \ingroup H5VLDEF
+ *
+ * \brief VOL connector identifiers.
+ *
+ * \details Values 0 through 255 are for connectors defined by the HDF5
+ *          library. Values 256 through 511 are available for testing new
+ *          connectors. Subsequent values should be obtained from the HDF5
+ *          development team at mailto:help@hdfgroup.org.
  */
+//! <!-- [H5VL_class_value_t_snip] -->
 typedef int H5VL_class_value_t;
+//! <!-- [H5VL_class_value_t_snip] -->
 
-/* Enum type for each VOL subclass */
-/* (Used for various queries, etc) */
+/**
+ * \ingroup H5VLDEF
+ * \details 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_SUBCLS_TOKEN     /* 'Token' subclass */
+    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_SUBCLS_TOKEN     /**< 'Token' subclass */
 } H5VL_subclass_t;
 
 /********************/
diff --git a/src/H5err.txt b/src/H5err.txt
index 63d6702..64452ec 100644
--- a/src/H5err.txt
+++ b/src/H5err.txt
@@ -80,6 +80,7 @@ MAJOR, H5E_PLUGIN, Plugin for dynamically loaded library
 MAJOR, H5E_PAGEBUF, Page Buffering
 MAJOR, H5E_CONTEXT, API Context
 MAJOR, H5E_MAP, Map
+MAJOR, H5E_EVENTSET, Event Set
 MAJOR, H5E_NONE_MAJOR, No error
 
 # Sections (for grouping minor errors)
@@ -104,6 +105,7 @@ SECTION, PIPELINE, I/O pipeline errors
 SECTION, SYSTEM, System level errors
 SECTION, PLUGIN, Plugin errors
 SECTION, MAP, Map related errors
+SECTION, ASYNC, Asynchronous I/O errors
 SECTION, NONE, No error
 
 # Minor errors
@@ -203,6 +205,7 @@ MINOR, BTREE, H5E_CANTINSERT, Unable to insert object
 MINOR, BTREE, H5E_CANTLIST, Unable to list node
 MINOR, BTREE, H5E_CANTMODIFY, Unable to modify record
 MINOR, BTREE, H5E_CANTREMOVE, Unable to remove object
+MINOR, BTREE, H5E_CANTFIND, Unable to check for record
 
 # Object header related errors
 MINOR, OHDR, H5E_LINKCOUNT, Bad object header link count
@@ -282,5 +285,11 @@ MINOR, SYSTEM, H5E_SYSERRSTR, System error message
 # Plugin errors
 MINOR, PLUGIN, H5E_OPENERROR, Can't open directory or file
 
+# Map related errors
+MINOR, MAP, H5E_CANTPUT, Can't put value
+
+# Asynchronous operation errors
+MINOR, ASYNC, H5E_CANTWAIT, Can't wait on operation
+
 # No error, for backward compatibility */
 MINOR, NONE, H5E_NONE_MINOR, No error
diff --git a/src/H5trace.c b/src/H5trace.c
index 00de4ed..d587853 100644
--- a/src/H5trace.c
+++ b/src/H5trace.c
@@ -1659,6 +1659,10 @@ H5_trace_args(H5RS_str_t *rs, const char *type, va_list ap)
                                                   (unsigned long long)obj);
                                 break;
 
+                            case H5I_EVENTSET:
+                                H5RS_asprintf_cat(rs, "0x%0llx (event set)", (unsigned long long)obj);
+                                break;
+
                             case H5I_NTYPES:
                                 H5RS_asprintf_cat(rs, "0x%0llx (ntypes - error)", (unsigned long long)obj);
                                 break;
@@ -1673,6 +1677,15 @@ H5_trace_args(H5RS_str_t *rs, const char *type, va_list ap)
 
                 case 'I':
                     switch (type[1]) {
+                        case 'D': /* H5I_future_discard_func_t */
+                        {
+                            H5I_future_discard_func_t ifdisc =
+                                (H5I_future_discard_func_t)HDva_arg(ap, H5I_future_discard_func_t);
+
+                            H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)ifdisc);
+                        } /* end block */
+                        break;
+
                         case 'f': /* H5I_free_t */
                         {
                             H5I_free_t ifree = (H5I_free_t)HDva_arg(ap, H5I_free_t);
@@ -1749,6 +1762,15 @@ H5_trace_args(H5RS_str_t *rs, const char *type, va_list ap)
                         }     /* end block */
                         break;
 
+                        case 'R': /* H5I_future_realize_func_t */
+                        {
+                            H5I_future_realize_func_t ifreal =
+                                (H5I_future_realize_func_t)HDva_arg(ap, H5I_future_realize_func_t);
+
+                            H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)ifreal);
+                        } /* end block */
+                        break;
+
                         case 's': /* int / int32_t */
                         {
                             int is = HDva_arg(ap, int);
@@ -1839,6 +1861,10 @@ H5_trace_args(H5RS_str_t *rs, const char *type, va_list ap)
                                     H5RS_acat(rs, "H5I_SPACE_SEL_ITER");
                                     break;
 
+                                case H5I_EVENTSET:
+                                    H5RS_acat(rs, "H5I_EVENTSET");
+                                    break;
+
                                 case H5I_NTYPES:
                                     H5RS_acat(rs, "H5I_NTYPES");
                                     break;
@@ -2959,6 +2985,10 @@ H5_trace_args(H5RS_str_t *rs, const char *type, va_list ap)
                                     H5RS_acat(rs, "H5VL_DATASET_REFRESH");
                                     break;
 
+                                case H5VL_DATASET_WAIT:
+                                    H5RS_acat(rs, "H5VL_DATASET_WAIT");
+                                    break;
+
                                 default:
                                     H5RS_asprintf_cat(rs, "%ld", (long)specific);
                                     break;
@@ -3083,6 +3113,10 @@ H5_trace_args(H5RS_str_t *rs, const char *type, va_list ap)
                                     H5RS_acat(rs, "H5VL_FILE_IS_EQUAL");
                                     break;
 
+                                case H5VL_FILE_WAIT:
+                                    H5RS_acat(rs, "H5VL_FILE_WAIT");
+                                    break;
+
                                 default:
                                     H5RS_asprintf_cat(rs, "%ld", (long)specific);
                                     break;
@@ -3295,6 +3329,34 @@ H5_trace_args(H5RS_str_t *rs, const char *type, va_list ap)
                         }     /* end block */
                         break;
 
+                        case 'r': /* H5VL_request_specific_t */
+                        {
+                            H5VL_request_specific_t specific = (H5VL_request_specific_t)HDva_arg(ap, int);
+
+                            switch (specific) {
+                                case H5VL_REQUEST_WAITANY:
+                                    H5RS_acat(rs, "H5VL_REQUEST_WAITANY");
+                                    break;
+
+                                case H5VL_REQUEST_WAITSOME:
+                                    H5RS_acat(rs, "H5VL_REQUEST_WAITSOME");
+                                    break;
+
+                                case H5VL_REQUEST_WAITALL:
+                                    H5RS_acat(rs, "H5VL_REQUEST_WAITALL");
+                                    break;
+
+                                case H5VL_REQUEST_GET_ERR_STACK:
+                                    H5RS_acat(rs, "H5VL_REQUEST_GET_ERR_STACK");
+                                    break;
+
+                                default:
+                                    H5RS_asprintf_cat(rs, "%ld", (long)specific);
+                                    break;
+                            } /* end switch */
+                        }     /* end block */
+                        break;
+
                         case 's': /* H5VL_attr_optional_t */
                         {
                             H5VL_attr_optional_t optional = (H5VL_attr_optional_t)HDva_arg(ap, int);
diff --git a/src/hdf5.h b/src/hdf5.h
index 2e7caf9..ab799e2 100644
--- a/src/hdf5.h
+++ b/src/hdf5.h
@@ -24,6 +24,7 @@
 #include "H5ACpublic.h" /* Metadata cache                           */
 #include "H5Dpublic.h"  /* Datasets                                 */
 #include "H5Epublic.h"  /* Errors                                   */
+#include "H5ESpublic.h" /* Event Sets                               */
 #include "H5Fpublic.h"  /* Files                                    */
 #include "H5FDpublic.h" /* File drivers                             */
 #include "H5Gpublic.h"  /* Groups                                   */