Merge branch 'feature/vfd_swmr' into multi

2 files changed, 20 insertions, 24 deletions

diff --git a/doc/VFD_SWMR_Guide.md b/doc/VFD_SWMR_Guide.md
deleted file mode 100644
index 4c70720..0000000
--- a/doc/VFD_SWMR_Guide.md
+++ /dev/null
@@ -1,24 +0,0 @@
-# VFD SWMR User's Guide
-
-## Caveats
-
-A few library functions are known to work incorrectly with VFD
-SWMR.
-
-* Variable-length data written using VFD SWMR may be inaccessible
-  or inconsistent to a VFD SWMR reader until the writer closes
-  the file.  Instead of the proper variable-length data, a reader may
-  read NULL or arbitrary bytes.  Inconsistencies may also cause the
-  reader to crash. 
-
-* Applications should take care using HDF5 iteration APIs, especially
-  when iterating large numbers of objects or using long-running
-  application callbacks.  While the library is in an iteration routine,
-  it does not track changes made by the writer.  If the library spends more than
-  `max_lag` ticks in the routine, then its view of the HDF5 file will become
-  stale.  Under those circumstances, HDF5 content could be mis-read, or the
-  library could crash with a diagnostic assertion.
-
-* At the present level of development, the writer cannot invalidate a reader's HDF5 object handles (`hid_t`s).  If a reader holds an object open---that is, it has a valid handle (`hid_t`) for the object---while the writer deletes it, then
-  reading content through the handle may yield corrupted data or the data from some
-  other object, or the library may crash.
diff --git a/doc/vfd-swmr-user-guide.md b/doc/vfd-swmr-user-guide.md
index 650d869..cfb6848 100644
--- a/doc/vfd-swmr-user-guide.md
+++ b/doc/vfd-swmr-user-guide.md
@@ -447,6 +447,26 @@ problem.  There is no schedule for those improvements.
 
 Improvements to VFD SWMR may also alleviate the problem.
 
+## Iteration
+
+An application that reads in VFD SWMR mode should take care to avoid
+HDF5 iteration APIs, especially when iterating large numbers of objects
+or using long-running application callbacks.  While the library is in an
+iteration routine, it cannot track changes made by the writer.  If the
+library spends more than `max_lag` ticks in the routine, then its view
+of the HDF5 file will become stale.  Under those circumstances, HDF5
+content could be mis-read, or the library could crash with a diagnostic
+assertion.
+
+## Object handles
+
+At the present level of development, the writer cannot invalidate
+a reader's HDF5 object handles (`hid_t`s).  If a reader holds an
+object open---that is, it has a valid handle (`hid_t`) for the
+object---while the writer deletes it, then reading content through
+the handle may yield corrupted data or the data from some other
+object, or the library may crash.
+
 ## Microsoft Windows 
 
 VFD SWMR is not officially supported on Microsoft Windows at this time.  The