Document vfd_swmr_writer_may_increase_tick_to() and

vfd_swmr_reader_did_increase_tick_to().  NFCI.

1 files changed, 31 insertions, 0 deletions

diff --git a/src/H5FDvfd_swmr_instr.c b/src/H5FDvfd_swmr_instr.c
index 865483c..da62351 100644
--- a/src/H5FDvfd_swmr_instr.c
+++ b/src/H5FDvfd_swmr_instr.c
@@ -14,6 +14,37 @@
 #include "H5Fpublic.h"
 #include "H5FDvfd_swmr.h"
 
+/* vfd_swmr_writer_may_increase_tick_to() and
+ * vfd_swmr_reader_did_increase_tick_to() are instrumentation points for
+ * VFD SWMR tests to use to coordinate the tick-number increases
+ * on a single writer with the progress of a single reader.
+ *
+ * This file provides the default, do-nothing implementations for both
+ * instrumentation routines.
+ *
+ * A VFD SWMR writer calls vfd_swmr_writer_may_increase_tick_to() with the
+ * increased tick number that it proposes, `tick_num`.  The argument
+ * `wait_for_reader` tells whether or not the writer can wait for the reader
+ * before increasing its tick number.  If `true`, then
+ * vfd_swmr_writer_may_increase_tick_to() should
+ * block until the reader is finished using the shadow-file content
+ * from ticks `tick_num - max_lag` and before, returning `true`.
+ * If `false`, then 
+ * vfd_swmr_writer_may_increase_tick_to() immediately return `true` if
+ * the new tick number does permissible, otherwise `false`.
+ *
+ * After a VFD SWMR reader increases its tick number, it calls
+ * vfd_swmr_reader_did_increase_tick_to() with the new tick number.
+ *
+ * The test programs test/vfd_swmr_zoo_{reader,writer} provide
+ * their own vfd_swmr_writer_may_increase_tick_to() and
+ * vfd_swmr_reader_did_increase_tick_to() implementations that override the
+ * ones in the library.  In the "zoo"
+ * test (test/vfd_swmr_zoo_{reader,writer}), the reader and the writer
+ * use a shared file to coordinate tick-number increases so that the writer
+ * can call H5Fvfd_swmr_end_tick() to increase its tick number at an arbitrary
+ * rate without outrunning the reader.
+ */
 bool
 vfd_swmr_writer_may_increase_tick_to(uint64_t H5_ATTR_UNUSED tick_num,
     bool H5_ATTR_UNUSED wait_for_reader)