Move the open issues noted in the outdated VFD_SWMR_Guide.md to

vfd-swmr-user-guide.md and delete VFD_SWMR_Guide.md.

1 files changed, 20 insertions, 0 deletions

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