Merge branch 'feature/vfd_swmr' into multi

2 files changed, 56 insertions, 7 deletions

diff --git a/src/H5FD.c b/src/H5FD.c
index c8b8da2..602b198 100644
--- a/src/H5FD.c
+++ b/src/H5FD.c
@@ -679,9 +679,18 @@ done:
     FUNC_LEAVE_API(ret_value)
 }
 
-/* Return `other` if `self` has no de-duplication method.  Otherwise, return
- * `other` if it duplicates `self`, `self` if `other` does NOT duplicate it,
- * NULL if `other` conflicts with `self` or if there is an error.
+/* Helper routine for H5FD_deduplicate(): compare `self` and `other` using
+ * the deduplication method of `self`, if it has one; otherwise compare using
+ * `H5FDcmp()`.
+ *
+ * If `self` has no de-duplication method, compare `self` and `other`
+ * using `H5FDcmp()` and return `self` if they're equal and `other` if
+ * unequal.
+ *
+ * If `self` does have a de-duplication method, call it and return the
+ * method's result: `other` if it duplicates `self`, `self` if `other`
+ * does NOT duplicate it, NULL if `other` conflicts with `self` or if
+ * there is an error.
  *
  * Unlike H5FD_deduplicate(), this routine does not free `self` under any
  * circumstances.
@@ -700,11 +709,19 @@ H5FD_dedup(H5FD_t *self, H5FD_t *other, hid_t fapl)
     return other;
 }
 
-/* If any other open H5FD_t is functionally equivalent to `file` under
- * the given file-access properties, then return it and close `file`.
+/* Search the already-opened VFD instances for an instance similar to the
+ * instance `file` newly-opened using file-access properties given by `fapl`.
+ *
+ * If there is an already-open instance that is functionally
+ * identical to `file`, close `file` and return the already-open instance.
+ *
+ * If there is an already-open instance that conflicts with `file` because,
+ * for example, its file-access properties are incompatible with `fapl`'s
+ * or, for another example, it is under exclusive control by a third VFD
+ * instance, then close `file` and return `NULL`.
  *
- * If any other open H5FD_t is not equivalent to `file`, but its
- * operation would conflict with `file`, then return NULL and close `file`.
+ * Otherwise, return `file` to indicate that there are no identical or
+ * conflicting VFD instances already open.
  */
 H5FD_t *
 H5FD_deduplicate(H5FD_t *file, hid_t fapl)
diff --git a/src/H5FDvfd_swmr.c b/src/H5FDvfd_swmr.c
index f0e0cfd..5322cf3 100644
--- a/src/H5FDvfd_swmr.c
+++ b/src/H5FDvfd_swmr.c
@@ -508,6 +508,38 @@ H5FD_vfd_swmr_cmp(const H5FD_t *_f1, const H5FD_t *_f2)
     FUNC_LEAVE_NOAPI(ret_value)
 } /* end H5FD_vfd_swmr_cmp() */
 
+/* Compare the already-opened VFD instance `_self` with the
+ * VFD instance `_other` newly-opened with file-access properties `fapl`
+ * and indicate whether the instances duplicate each other, if they conflict
+ * with each other, or if they are dissimilar.
+ *
+ * If `_self` duplicates `_other`, return `_self`.
+ *
+ * Return NULL on error, or if `_other` and `_self` refer to the same file
+ * but the file-access properties, `fapl`, conflict with the properties of
+ * `_self`.
+ *
+ * If `_other` neither duplicates nor conflicts with `_self`, then return
+ * `_other`.
+ *
+ * # Judging duplicate/conflicting/dissimilar VFD instances
+ *
+ * `_self` duplicates `_other` if `_other` is also an instance of SWMR
+ * class, the instances' lower files are equal under `H5FD_cmp()`, and
+ * the file-access properties of `_self` match `fapl`.
+ * The wildcard `fapl` value, `H5P_FILE_ACCESS_ANY_VFD`, matches all.
+ *
+ * `_self` also duplicates `_other` if `_other` is not a SWMR instance, but
+ * it equals the lower file of `_self` under `H5FD_cmp()`, and `fapl` is
+ * `H5P_FILE_ACCESS_ANY_VFD`.
+ *
+ * `_self` and `_other` conflict if both are SWMR instances referring to
+ * the same lower file, and their file-access properties differ.
+ *
+ * `_self` and `_other` conflict if `_other` is not a SWMR instance, it
+ * equals the lower file of `_self`, and `fapl` is not equal to
+ * `H5P_FILE_ACCESS_ANY_VFD`.
+ */
 static H5FD_t *
 H5FD_vfd_swmr_dedup(H5FD_t *_self, H5FD_t *_other, hid_t fapl)
 {