[svn-r19714] Purpose:

    Add API and supporting code to allow single object flushes and refreshes.

Description:

    Added the following API calls:

    H5Dflush / H5Drefresh
    H5Gflush / H5Grefresh
    H5Tflush / H5Trefresh
    H5Oflush / H5Orefresh

    Each H5*flush API flushes the targeted object's metadata, 
    while each H5*refresh evicts all metadata related to an object 
    and reopens the object (re-loading needed metadata from disk).

    New files include src/H5Oflush.c, containing new internal H5O_* 
    functions used by the above API calls. Also, a test file and test 
    script template have been added, test/flushrefresh.c and 
    test/testflushrefresh.sh.in. There is not (yet) a corresponding 
    test script for windows as the current one isn't quite portable.

    Several H5C and H5AC-level functions have been added to support 
    single object flushing and eviction, and the previously committed 
    'metadata tagging' code has been tweaked slightly to pull H5AC__* 
    macros out of H5C.c and a few other fixes as necessary as well.

    Tag globality has been added to better encapsulate the meaning of 
    global tags in the H5C layer of the code. 

Tested:

    h5committested.

1 files changed, 211 insertions, 4 deletions

diff --git a/src/H5AC.c b/src/H5AC.c
index cba1615..e0813be 100644
--- a/src/H5AC.c
+++ b/src/H5AC.c
@@ -127,6 +127,10 @@ static herr_t H5AC_check_if_write_permitted(const H5F_t *f,
 
 static herr_t H5AC_ext_config_2_int_config(H5AC_cache_config_t * ext_conf_ptr,
                                            H5C_auto_size_ctl_t * int_conf_ptr);
+                                           
+#if H5AC_DO_TAGGING_SANITY_CHECKS
+static herr_t H5AC_verify_tag(hid_t dxpl_id, H5AC_class_t * type);
+#endif /* H5AC_DO_TAGGING_SANITY_CHECKS */
 
 #ifdef H5_HAVE_PARALLEL
 static herr_t H5AC_broadcast_candidate_list(H5AC_t * cache_ptr,
@@ -990,6 +994,11 @@ H5AC_insert_entry(H5F_t *f, hid_t dxpl_id, const H5AC_class_t *type, haddr_t add
     }
 #endif /* H5AC__TRACE_FILE_ENABLED */
 
+#if H5AC_DO_TAGGING_SANITY_CHECKS
+    if (!f->shared->cache->ignore_tags && (H5AC_verify_tag(dxpl_id, type) < 0))
+        HGOTO_ERROR(H5E_CACHE, H5E_CANTTAG, FAIL, "Bad tag value")
+#endif /* H5AC_DO_TAGGING_SANITY_CHECKS */
+
     /* Insert entry into metadata cache */
     if(H5C_insert_entry(f, dxpl_id, H5AC_noblock_dxpl_id, type, addr, thing, flags) < 0)
         HGOTO_ERROR(H5E_CACHE, H5E_CANTINS, FAIL, "H5C_insert_entry() failed")
@@ -1375,6 +1384,11 @@ H5AC_protect(H5F_t *f,
 	protect_flags |= H5C__READ_ONLY_FLAG;
     }
 
+#if H5AC_DO_TAGGING_SANITY_CHECKS
+    if (!f->shared->cache->ignore_tags && (H5AC_verify_tag(dxpl_id, type) < 0))
+        HGOTO_ERROR(H5E_CACHE, H5E_CANTTAG, NULL, "Bad tag value")
+#endif /* H5AC_DO_TAGGING_SANITY_CHECKS */
+
     thing = H5C_protect(f,
 		        dxpl_id,
                         H5AC_noblock_dxpl_id,
@@ -5226,8 +5240,9 @@ herr_t
 H5AC_tag(hid_t dxpl_id, haddr_t metadata_tag, haddr_t * prev_tag)
 {
     /* Variable Declarations */
-    H5P_genplist_t *dxpl;    /* dataset transfer property list */
-    herr_t ret_value = SUCCEED;
+    H5P_genplist_t *dxpl = NULL;    /* dataset transfer property list */
+    int globality = 0;         /* global tag value */
+    herr_t ret_value = SUCCEED;     /* return value */
 
     /* Function Enter Macro */
     FUNC_ENTER_NOAPI(H5AC_tag, FAIL)
@@ -5245,6 +5260,25 @@ H5AC_tag(hid_t dxpl_id, haddr_t metadata_tag, haddr_t * prev_tag)
     /* Set the provided tag value in the dxpl_id. */
     if(H5P_set(dxpl, "H5AC_metadata_tag", &metadata_tag) < 0)
         HGOTO_ERROR(H5E_PLIST, H5E_CANTSET, FAIL, "can't set property in dxpl")
+    
+    /* Determine globality of tag */
+    switch(metadata_tag) {
+        case H5AC__SUPERBLOCK_TAG:
+        case H5AC__SOHM_TAG:
+        case H5AC__GLOBALHEAP_TAG:
+            globality = H5C_GLOBALITY_MAJOR;
+            break;
+        case H5AC__FREESPACE_TAG:
+            globality = H5C_GLOBALITY_MINOR;
+            break;
+        default:
+            globality = H5C_GLOBALITY_NONE;
+            break;
+    } /* end switch */
+
+    /* Set globality in dxpl */
+    if(H5P_set(dxpl, "H5C_tag_globality", &globality) < 0)
+        HGOTO_ERROR(H5E_PLIST, H5E_CANTSET, FAIL, "can't set property in dxpl")
 
 done:
     FUNC_LEAVE_NOAPI(ret_value)
@@ -5277,10 +5311,183 @@ H5AC_retag_copied_metadata(H5F_t * f, haddr_t metadata_tag)
     HDassert(f);
     HDassert(f->shared);
      
-    /* Call cache-level function to retag entries */
-    H5C_retag_copied_metadata(f->shared->cache, metadata_tag);
+    /* Call cache-level function to re-tag entries with the COPIED tag */
+    H5C_retag_metadata(f->shared->cache, H5AC__COPIED_TAG, metadata_tag);
 
 done:
     FUNC_LEAVE_NOAPI(ret_value)
 } /* H5AC_retag_copied_metadata */
 
+
+/*------------------------------------------------------------------------------
+ * Function:    H5AC_flush_tagged_metadata()
+ *
+ * Purpose:     Wrapper for cache level function which flushes all metadata
+ *              that contains the specific tag. 
+ * 
+ * Return:      SUCCEED on success, FAIL otherwise.
+ *
+ * Programmer:  Mike McGreevy
+ *              May 19, 2010
+ *
+ *------------------------------------------------------------------------------
+ */
+herr_t
+H5AC_flush_tagged_metadata(H5F_t * f, haddr_t metadata_tag, hid_t dxpl_id)
+{
+    /* Variable Declarations */
+    herr_t ret_value = SUCCEED;
+    herr_t result;
+ 
+    /* Function Enter Macro */   
+    FUNC_ENTER_NOAPI(H5AC_flush_tagged_metadata, FAIL)
+
+    /* Assertions */
+    HDassert(f);
+    HDassert(f->shared);
+
+    /* Call cache level function to flush metadata entries with specified tag */
+    if(H5C_flush_tagged_entries(f, dxpl_id, H5AC_dxpl_id, metadata_tag)<0)
+        HGOTO_ERROR(H5E_CACHE, H5E_CANTFLUSH, FAIL, "Cannot flush metadata")
+
+done:
+    FUNC_LEAVE_NOAPI(ret_value)
+
+} /* H5AC_flush_tagged_metadata */
+
+
+/*------------------------------------------------------------------------------
+ * Function:    H5AC_evict_tagged_metadata()
+ *
+ * Purpose:     Wrapper for cache level function which flushes all metadata
+ *              that contains the specific tag. 
+ * 
+ * Return:      SUCCEED on success, FAIL otherwise.
+ *
+ * Programmer:  Mike McGreevy
+ *              May 19, 2010
+ *
+ *------------------------------------------------------------------------------
+ */
+herr_t
+H5AC_evict_tagged_metadata(H5F_t * f, haddr_t metadata_tag, hid_t dxpl_id)
+{
+    /* Variable Declarations */
+    herr_t ret_value = SUCCEED;
+ 
+    /* Function Enter Macro */   
+    FUNC_ENTER_NOAPI(H5AC_evict_tagged_metadata, FAIL)
+
+    /* Assertions */
+    HDassert(f);
+    HDassert(f->shared);
+
+    /* Call cache level function to evict metadata entries with specified tag */
+    if(H5C_evict_tagged_entries(f, dxpl_id, H5AC_dxpl_id, metadata_tag)<0)
+        HGOTO_ERROR(H5E_CACHE, H5E_CANTFLUSH, FAIL, "Cannot evict metadata")
+
+done:
+    FUNC_LEAVE_NOAPI(ret_value)
+
+} /* H5AC_evict_tagged_metadata */
+
+#if H5AC_DO_TAGGING_SANITY_CHECKS
+
+/*-------------------------------------------------------------------------
+ *
+ * Function:    H5AC_verify_tag
+ *
+ * Purpose:     Performs sanity checking on an entry type and tag value
+ *              stored in a supplied dxpl_id.
+ *
+ * Return:      SUCCEED or FAIL.
+ *
+ * Programmer:  Mike McGreevy
+ *              October 20, 2010
+ *
+ *-------------------------------------------------------------------------
+ */
+static herr_t
+H5AC_verify_tag(hid_t dxpl_id, H5AC_class_t * type)
+{
+    haddr_t tag = HADDR_UNDEF;
+    int globality = -1;
+    H5P_genplist_t * dxpl;
+    herr_t ret_value = SUCCEED;
+
+    FUNC_ENTER_NOAPI(H5AC_verify_tag, FAIL)
+
+    /* Get the dataset transfer property list */
+    if(NULL == (dxpl = (H5P_genplist_t *)H5I_object_verify(dxpl_id, H5I_GENPROP_LST)))
+        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a property list")
+
+    /* Get the tag from the DXPL */
+    if( (H5P_get(dxpl, "H5AC_metadata_tag", &tag)) < 0 )
+        HGOTO_ERROR(H5E_PLIST, H5E_CANTGET, FAIL, "unable to query property value");
+
+    /* Get the tag globality from the DXPL */
+    if( (H5P_get(dxpl, "H5C_tag_globality", &globality)) < 0 )
+        HGOTO_ERROR(H5E_PLIST, H5E_CANTGET, FAIL, "unable to query property value");
+
+    /* Perform some sanity checks on tag value. Certain entry
+     * types require certain tag values, so check that these
+     * constraints are met. */
+    if(tag == H5AC__IGNORE_TAG)
+        HGOTO_ERROR(H5E_CACHE, H5E_CANTTAG, FAIL, "cannot ignore a tag while doing verification.")
+    else if(tag == H5AC__INVALID_TAG)
+        HGOTO_ERROR(H5E_CACHE, H5E_CANTTAG, FAIL, "no metadata tag provided")
+    else {
+
+        /* Perform some sanity checks on tag value. Certain entry
+         * types require certain tag values, so check that these
+         * constraints are met. */
+
+        /* Superblock */
+        if(type->id == H5AC_SUPERBLOCK_ID) {
+            if(tag != H5AC__SUPERBLOCK_TAG)
+                HGOTO_ERROR(H5E_CACHE, H5E_CANTTAG, FAIL, "superblock not tagged with H5AC__SUPERBLOCK_TAG")
+            if(globality != H5C_GLOBALITY_MAJOR)
+                HGOTO_ERROR(H5E_CACHE, H5E_CANTTAG, FAIL, "superblock globality not marked with H5C_GLOBALITY_MAJOR")
+        }
+        else {
+            if(tag == H5AC__SUPERBLOCK_TAG)
+                HGOTO_ERROR(H5E_CACHE, H5E_CANTTAG, FAIL, "H5AC__SUPERBLOCK_TAG applied to non-superblock entry")
+        }
+    
+        /* Free Space Manager */
+        if((type->id == H5AC_FSPACE_HDR_ID) || (type->id == H5AC_FSPACE_SINFO_ID)) {
+            if(tag != H5AC__FREESPACE_TAG)
+                HGOTO_ERROR(H5E_CACHE, H5E_CANTTAG, FAIL, "freespace entry not tagged with H5AC__FREESPACE_TAG")
+            if(globality != H5C_GLOBALITY_MINOR)
+                HGOTO_ERROR(H5E_CACHE, H5E_CANTTAG, FAIL, "freespace entry globality not marked with H5C_GLOBALITY_MINOR")
+        }
+        else {
+            if(tag == H5AC__FREESPACE_TAG)
+                HGOTO_ERROR(H5E_CACHE, H5E_CANTTAG, FAIL, "H5AC__FREESPACE_TAG applied to non-freespace entry")
+        }
+    
+        /* SOHM */
+        if((type->id == H5AC_SOHM_TABLE_ID) || (type->id == H5AC_SOHM_LIST_ID)) { 
+            if(tag != H5AC__SOHM_TAG)
+                HGOTO_ERROR(H5E_CACHE, H5E_CANTTAG, FAIL, "sohm entry not tagged with H5AC__SOHM_TAG")
+            if(globality != H5C_GLOBALITY_MAJOR)
+                HGOTO_ERROR(H5E_CACHE, H5E_CANTTAG, FAIL, "sohm entry globality not marked with H5C_GLOBALITY_MAJOR")
+        }
+    
+        /* Global Heap */
+        if(type->id == H5AC_GHEAP_ID) {
+            if(tag != H5AC__GLOBALHEAP_TAG)
+                HGOTO_ERROR(H5E_CACHE, H5E_CANTTAG, FAIL, "global heap not tagged with H5AC__GLOBALHEAP_TAG")
+            if(globality != H5C_GLOBALITY_MAJOR)
+                HGOTO_ERROR(H5E_CACHE, H5E_CANTTAG, FAIL, "global heap entry globality not marked with H5C_GLOBALITY_MAJOR")
+        }
+        else {
+            if(tag == H5AC__GLOBALHEAP_TAG)
+                HGOTO_ERROR(H5E_CACHE, H5E_CANTTAG, FAIL, "H5AC__GLOBALHEAP_TAG applied to non-globalheap entry")
+        }
+    } /* end else */
+
+done:
+    FUNC_LEAVE_NOAPI(ret_value)
+} /* H5AC_verify_tag */
+#endif /* H5AC_DO_TAGGING_SANITY_CHECKS */