Add/improve some struct/member documentation per John's request.

5 files changed, 56 insertions, 37 deletions

diff --git a/src/H5FDprivate.h b/src/H5FDprivate.h
index 0d05b15..8acbd30 100644
--- a/src/H5FDprivate.h
+++ b/src/H5FDprivate.h
@@ -157,6 +157,15 @@
  *              lower file and is therefore about to be removed from the
  *              metadata file
  *
+ * garbage: `true` if the entry is marked for garbage collection and is
+ *              thus invalid.
+ *
+ *              For n the number of entries, deleting an entry is O(n).
+ *              H5PB_dest() deletes all entries.  Instead of deleting
+ *              entries one-by-one at O(n^2) cost, H5PB_dest() marks
+ *              each disused entry for garbage collection and sweeps all
+ *              entries up before it is done.
+ *
  *----------------------------------------------------------------------------
  */
 typedef struct H5FD_vfd_swmr_idx_entry_t {
diff --git a/src/H5FDvfd_swmr.c b/src/H5FDvfd_swmr.c
index e2f8513..5d2474f 100644
--- a/src/H5FDvfd_swmr.c
+++ b/src/H5FDvfd_swmr.c
@@ -53,13 +53,21 @@ typedef struct H5FD_vfd_swmr_t {
     uint32_t api_elapsed_nslots;
     uint64_t *api_elapsed_ticks;            /* Histogram of ticks elapsed
                                              * inside the API (reader only).
+                                             * api_elapsed_ticks[elapsed] is
+                                             * the number of times `elapsed`
+                                             * ticks passed in an API call
+                                             * during the program lifetime.
                                              */
     hbool_t pb_configured;                      /* boolean flag set to TRUE   */
                                                 /* when the page buffer is    */
                                                 /* and to FALSE otherwise.    */
                                                 /* Used for sanity checking.  */
     H5F_vfd_swmr_config_t config;
-    bool writer;                            /* True iff configured to write. */
+    bool writer;                            /* True iff configured to write.
+                                             * All methods on a write-mode
+                                             * SWMR VFD instance are passed
+                                             * to the lower VFD instance.
+                                             */
 } H5FD_vfd_swmr_t;
 
 #define MAXADDR (((haddr_t)1<<(8*sizeof(HDoff_t)-1))-1)
diff --git a/src/H5FDvfd_swmr_private.h b/src/H5FDvfd_swmr_private.h
index 67a72ec..74a937f 100644
--- a/src/H5FDvfd_swmr_private.h
+++ b/src/H5FDvfd_swmr_private.h
@@ -53,7 +53,7 @@ typedef struct eot_queue_entry {
     hbool_t     vfd_swmr_writer;
     uint64_t    tick_num;
     struct timespec end_of_tick;
-    struct H5F_t  *vfd_swmr_file; /* NOTE: for the time being use H5F_t instead H5F_file_t */
+    struct H5F_t  *vfd_swmr_file; /* NOTE: for the time being use H5F_t instead H5F_shared_t */
     TAILQ_ENTRY(eot_queue_entry) link;
 } eot_queue_entry_t;
 
diff --git a/src/H5Fpkg.h b/src/H5Fpkg.h
index 1136cb4..71d0ce4 100644
--- a/src/H5Fpkg.h
+++ b/src/H5Fpkg.h
@@ -217,24 +217,14 @@ typedef struct H5F_mtab_t {
     H5F_mount_t		*child;	/* An array of mount records		*/
 } H5F_mtab_t;
 
-/* 
- *  VFD SWMR: Entry for the delayed free space release doubly linked list 
- *
- *  md_file_page_offset:    Unsigned 64-bit value containing the base address
- *                          of the metadata page, or multi page metadata entry
- *                          in the metadata file IN PAGES.
- *                          To obtain byte offset, multiply this value by the
- *                          page size.
- *  length:                 The length of the metadata page or multi page
- *                          metadata entry in BYTES.
- *  tick_num:               Sequence # of the current tick
- *  link:                   tailqueue linkage
+/* Deferred-free record for the shadow file: records a region of bytes in
+ * the shadow file to release after max_lag ticks.
  */
 typedef struct shadow_defree {
-    uint64_t offset;
-    uint32_t length;
-    uint64_t tick_num;                     
-    TAILQ_ENTRY(shadow_defree) link;
+    uint64_t offset;            // offset of the region in *bytes*
+    uint32_t length;            // length of the region in *bytes*
+    uint64_t tick_num;          // tick number when the free was deferred
+    TAILQ_ENTRY(shadow_defree) link;    // deferred-free queue linkage
 } shadow_defree_t;
 
 /* Structure specifically to store superblock. This was originally
@@ -256,17 +246,27 @@ typedef struct H5F_super_t {
     H5G_entry_t *root_ent;      /* Root group symbol table entry              */
 } H5F_super_t;
 
-/* VFD SWMR: deferred free on the lower VFD. */
+/* Deferred-free record for the lower file: records a region of bytes in
+ * the file below the SWMR VFD to release after a delay.
+ */
 typedef struct lower_defree {
-    SIMPLEQ_ENTRY(lower_defree) link;
-    H5FD_mem_t alloc_type;
-    haddr_t addr;
-    hsize_t size;
-    uint64_t free_after_tick;
+    SIMPLEQ_ENTRY(lower_defree) link;   // deferred-free queue linkage
+    H5FD_mem_t alloc_type;      // type with which the region was allocated
+    haddr_t addr;               // start of the region *in bytes*
+    hsize_t size;               // length of the region *in bytes*
+    uint64_t free_after_tick;   /* the region may be reused on tick
+                                 * free_after_tick + 1 at the earliest
+                                 */
 } lower_defree_t;
 
+/* Queue of deferred-free records (lower_defree_t) for the lower file, sorted
+ * head-to-tail in increasing `free_after_tick` order.
+ */
 typedef SIMPLEQ_HEAD(lower_defree_queue, lower_defree) lower_defree_queue_t;
 
+/* Queue of deferred-free records (shadow_defree_t) for the shadow file, sorted
+ * head-to-tail in increasing `tick_num` order.
+ */
 typedef TAILQ_HEAD(shadow_defree_queue, shadow_defree) shadow_defree_queue_t;
 
 /*
@@ -403,7 +403,9 @@ struct H5F_shared_t {
                                              * configuration from the
                                              * FAPL used to open the file 
                                              */
-    haddr_t writer_index_offset;
+    haddr_t writer_index_offset;            /* Current byte offset of the
+                                             * shadow index in the shadow file.
+                                             */
     hbool_t vfd_swmr;                       /* The file is opened with VFD 
                                              * SWMR configured or not
                                              */
@@ -413,7 +415,9 @@ struct H5F_shared_t {
     uint64_t tick_num;                      /* Number of the current tick */
     struct timespec end_of_tick;            /* End time of the current tick */
 
-    lower_defree_queue_t lower_defrees;    /* For use by VFD SWMR writers. */
+    lower_defree_queue_t lower_defrees;    /* Records of lower-file space
+                                            * awaiting reclamation.
+                                            */
     /* VFD SWMR metadata file index */
     H5FD_vfd_swmr_idx_entry_t * mdf_idx;    /* pointer to an array of instance
                                              * of H5FD_vfd_swmr_idx_entry_t of 
diff --git a/src/H5Fpublic.h b/src/H5Fpublic.h
index d4f6341..17d8ce1 100644
--- a/src/H5Fpublic.h
+++ b/src/H5Fpublic.h
@@ -260,17 +260,15 @@ typedef herr_t (*H5F_flush_cb_t)(hid_t object_id, void *udata);
  *          is selected.
  *
  *      md_pages_reserved:
- *          An integer field indicating the number of pages reserved 
- *          at the head of the metadata file.  This value must be greater than 
- *          or equal to 1.  
- *          When the metadata file is created, the specified number of pages is 
- *          reserved at the head of the metadata file.  In the current
- *          implementation, the size of the metadata file header plus the 
- *          index is limited to this size.
- *          Further, in the POSIX case, when readers check for an updated index, 
- *          this check will start with a read of md_pages_reserved pages from
- *          the head of the metadata file.
- *         
+ *          The `md_pages_reserved` parameter tells how many pages to reserve
+ *          at the beginning of the shadow file for the shadow-file header
+ *          and the shadow index.  The header has an entire page to itself.
+ *          The remaining `md_pages_reserved - 1` pages are reserved for the
+ *          shadow index.  If the index grows larger than its initial
+ *          allocation, then it will move to a new location in the shadow file,
+ *          and the initial allocation will be reclaimed.  `md_pages_reserved`
+ *          must be at least 2.
+ *
  *      pb_expansion_threshold:
  *          An integer field indicating the threshold for the page buffer size.
  *          During a tick, the page buffer must expand as necessary to retain copies