From fd406a654c1c0796af8624c5b022dcc29cf209ec Mon Sep 17 00:00:00 2001 From: David Young Date: Mon, 31 Aug 2020 15:46:47 -0500 Subject: Document vfd_swmr_writer_may_increase_tick_to() and vfd_swmr_reader_did_increase_tick_to(). NFCI. --- src/H5FDvfd_swmr_instr.c | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) 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) -- cgit v0.12