Update Guide. Switch to a short and informative function name.

1 files changed, 12 insertions, 0 deletions

diff --git a/doc/VFD_SWMR_Guide.md b/doc/VFD_SWMR_Guide.md
index 22dd0ca..4c70720 100644
--- a/doc/VFD_SWMR_Guide.md
+++ b/doc/VFD_SWMR_Guide.md
@@ -10,3 +10,15 @@ SWMR.
   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.