Align w/minor cleanups in revise_chunks branch.

1 files changed, 51 insertions, 24 deletions

diff --git a/src/H5Cpkg.h b/src/H5Cpkg.h
index 10180b9..78ae930 100644
--- a/src/H5Cpkg.h
+++ b/src/H5Cpkg.h
@@ -3154,7 +3154,32 @@ if ( ( (entry_ptr) == NULL ) ||                                                \
 /* Package Private Typedefs */
 /****************************/
 
-/* Info about each set of tagged entries */
+/****************************************************************************
+ *
+ * structure H5C_tag_info_t
+ *
+ * Structure about each set of tagged entries for an object in the file.
+ *
+ * Each H5C_tag_info_t struct corresponds to a particular object in the file.
+ *
+ * Each H5C_cache_entry struct in the linked list of entries for this tag
+ *      also contains a pointer back to the H5C_tag_info_t struct for the
+ *      overall object.
+ *
+ *
+ * The fields of this structure are discussed individually below:
+ *
+ * tag:	Address (i.e. "tag") of the object header for all the entries
+ *              corresponding to parts of that object.
+ *
+ * head: Head of doubly-linked list of all entries belonging to the tag.
+ *
+ * entry_cnt: Number of entries on linked list of entries for this tag.
+ *
+ * corked: Boolean flag indicating whether entries for this object can be
+ * 		evicted.
+ *
+ ****************************************************************************/
 typedef struct H5C_tag_info_t {
     haddr_t tag;                /* Tag (address) of the entries (must be first, for skiplist) */
     H5C_cache_entry_t *head;    /* Head of the list of entries for this tag */
@@ -3162,6 +3187,7 @@ typedef struct H5C_tag_info_t {
     hbool_t corked;             /* Whether this object is corked */
 } H5C_tag_info_t;
 
+
 /****************************************************************************
  *
  * structure H5C_t
@@ -3429,14 +3455,6 @@ typedef struct H5C_tag_info_t {
  *              (This functions similarly to a "dead man's switch")
  *
  *
- * With the addition of cache entry tagging, it is possible that 
- * an entry may be inserted into the cache without a tag during testing
- * and the tag's validity shouldn't be checked.
- *
- * The following field is maintained to facilitate this.
- *
- * ignore_tags:	Boolean flag to disable tag validation during entry insertion.
- *
  * When we flush the cache, we need to write entries out in increasing
  * address order.  An instance of a skip list is used to store dirty entries in
  * sorted order.  Whether it is cheaper to sort the dirty entries as needed,
@@ -3513,11 +3531,22 @@ typedef struct H5C_tag_info_t {
  * 		to the slist since the last time this field was set to
  * 		zero.  Note that this value can be negative.
  *
- * cork_list_ptr: A skip list to track object addresses that are corked.
- *                When an entry is inserted or protected in the cache,
- *                the entry's associated object address (tag field) is
- *                checked against this skip list.  If found, the entry
- *                is corked.
+ * Cache entries belonging to a particular object are "tagged" with that
+ * object's base object header address.
+ *
+ * The following fields are maintained to facilitate this.
+ *
+ * tag_list: A skip list to track entries that belong to an object.
+ *                Each H5C_tag_info_t struct on the tag list corresponds to
+ *                a particular object in the file.  Tagged entries can be
+ *                flushed or evicted as a group, or corked to prevent entries
+ *                from being evicted from the cache.
+ *
+ *                "Global" entries, like the superblock and the file's
+ *                freelist, as well as shared entries like global
+ *                heaps and shared object header messages, are not tagged.
+ *
+ * ignore_tags:	Boolean flag to disable tag validation during entry insertion.
  *
  * When a cache entry is protected, it must be removed from the LRU
  * list(s) as it cannot be either flushed or evicted until it is unprotected.
@@ -3742,13 +3771,6 @@ typedef struct H5C_tag_info_t {
  *              all the ways this can happen, we simply set this flag when
  *              we receive a new configuration.
  *
- * cache_full:	Boolean flag used to keep track of whether the cache is
- *		full, so we can refrain from increasing the size of a
- *		cache which hasn't used up the space allotted to it.
- *
- *		The field is initialized to FALSE, and then set to TRUE
- *		whenever we attempt to make space in the cache.
- *
  * resize_enabled:  This is another convenience flag which is set whenever
  *		a new set of values for resize_ctl are provided.  Very
  *		simply,
@@ -3756,6 +3778,13 @@ typedef struct H5C_tag_info_t {
  *		    resize_enabled = size_increase_possible ||
  *                                   size_decrease_possible;
  *
+ * cache_full:	Boolean flag used to keep track of whether the cache is
+ *		full, so we can refrain from increasing the size of a
+ *		cache which hasn't used up the space allotted to it.
+ *
+ *		The field is initialized to FALSE, and then set to TRUE
+ *		whenever we attempt to make space in the cache.
+ *
  * size_decreased:  Boolean flag set to TRUE whenever the maximum cache
  *		size is decreased.  The flag triggers a call to
  *		H5C_make_space_in_cache() on the next call to H5C_protect().
@@ -4128,9 +4157,6 @@ struct H5C_t {
     H5C_cache_entry_t *		last_entry_removed_ptr;
     H5C_cache_entry_t *		entry_watched_for_removal;
 
-    /* Field to disable tag validation */
-    hbool_t                     ignore_tags;
-
     /* Fields for maintaining list of in-order entries, for flushing */
     hbool_t			slist_changed;
     int32_t                     slist_len;
@@ -4146,6 +4172,7 @@ struct H5C_t {
 
     /* Fields for maintaining list of tagged entries */
     H5SL_t *                    tag_list;
+    hbool_t                     ignore_tags;
 
     /* Fields for tracking protected entries */
     int32_t                     pl_len;