[svn-r12595] Modified H5C_insert_entry() to accept the H5C__PIN_ENTRY_FLAG entry

flag, and pin an entry as it is inserted.

The objective is to avoid some function call overhead in fheap.

Also added matching test code in test/cache.c & test/cache_common.c
(also testpar/t_cache.c checked in separately by accident)

h5commit tested

6 files changed, 506 insertions, 83 deletions

diff --git a/src/H5ACprivate.h b/src/H5ACprivate.h
index a1c8322..fd6a073 100644
--- a/src/H5ACprivate.h
+++ b/src/H5ACprivate.h
@@ -226,16 +226,17 @@ extern hid_t H5AC_ind_dxpl_id;
  * the equivalent flags from H5Cprivate.h.
  */
 
-#define H5AC__NO_FLAGS_SET		H5C__NO_FLAGS_SET
-#define H5AC__SET_FLUSH_MARKER_FLAG	H5C__SET_FLUSH_MARKER_FLAG
-#define H5AC__DELETED_FLAG		H5C__DELETED_FLAG
-#define H5AC__DIRTIED_FLAG		H5C__DIRTIED_FLAG
-#define H5AC__SIZE_CHANGED_FLAG		H5C__SIZE_CHANGED_FLAG
-#define H5AC__PIN_ENTRY_FLAG		H5C__PIN_ENTRY_FLAG
-#define H5AC__UNPIN_ENTRY_FLAG		H5C__UNPIN_ENTRY_FLAG
-#define H5AC__FLUSH_INVALIDATE_FLAG	H5C__FLUSH_INVALIDATE_FLAG
-#define H5AC__FLUSH_CLEAR_ONLY_FLAG	H5C__FLUSH_CLEAR_ONLY_FLAG
-#define H5AC__FLUSH_MARKED_ENTRIES_FLAG	H5C__FLUSH_MARKED_ENTRIES_FLAG
+#define H5AC__NO_FLAGS_SET		  H5C__NO_FLAGS_SET
+#define H5AC__SET_FLUSH_MARKER_FLAG	  H5C__SET_FLUSH_MARKER_FLAG
+#define H5AC__DELETED_FLAG		  H5C__DELETED_FLAG
+#define H5AC__DIRTIED_FLAG		  H5C__DIRTIED_FLAG
+#define H5AC__SIZE_CHANGED_FLAG		  H5C__SIZE_CHANGED_FLAG
+#define H5AC__PIN_ENTRY_FLAG		  H5C__PIN_ENTRY_FLAG
+#define H5AC__UNPIN_ENTRY_FLAG		  H5C__UNPIN_ENTRY_FLAG
+#define H5AC__FLUSH_INVALIDATE_FLAG	  H5C__FLUSH_INVALIDATE_FLAG
+#define H5AC__FLUSH_CLEAR_ONLY_FLAG	  H5C__FLUSH_CLEAR_ONLY_FLAG
+#define H5AC__FLUSH_MARKED_ENTRIES_FLAG   H5C__FLUSH_MARKED_ENTRIES_FLAG
+#define H5AC__FLUSH_IGNORE_PROTECTED_FLAG H5C__FLUSH_IGNORE_PROTECTED_FLAG
 
 
 /* #defines of flags used to report entry status in the
diff --git a/src/H5C.c b/src/H5C.c
index 8283d77..9e5cfb0 100644
--- a/src/H5C.c
+++ b/src/H5C.c
@@ -533,6 +533,9 @@ if ( ( (entry_ptr) == NULL ) ||                                                \
  * 	JRM -- 3/21/06
  * 	Added / updated macros for pinned entry related stats.
  *
+ * 	JRM -- 8/9/06
+ * 	More pinned entry stats related updates.
+ *
  ***********************************************************************/
 
 #define H5C__UPDATE_CACHE_HIT_RATE_STATS(cache_ptr, hit) \
@@ -546,22 +549,6 @@ if ( ( (entry_ptr) == NULL ) ||                                                \
 #define H5C__UPDATE_STATS_FOR_DIRTY_PIN(cache_ptr, entry_ptr) \
 	(((cache_ptr)->dirty_pins)[(entry_ptr)->type->id])++;
 
-#define H5C__UPDATE_STATS_FOR_INSERTION(cache_ptr, entry_ptr)        \
-	(((cache_ptr)->insertions)[(entry_ptr)->type->id])++;        \
-        if ( (cache_ptr)->index_len > (cache_ptr)->max_index_len )   \
-	    (cache_ptr)->max_index_len = (cache_ptr)->index_len;     \
-        if ( (cache_ptr)->index_size > (cache_ptr)->max_index_size ) \
-	    (cache_ptr)->max_index_size = (cache_ptr)->index_size;   \
-        if ( (cache_ptr)->slist_len > (cache_ptr)->max_slist_len )   \
-	    (cache_ptr)->max_slist_len = (cache_ptr)->slist_len;     \
-        if ( (cache_ptr)->slist_size > (cache_ptr)->max_slist_size ) \
-	    (cache_ptr)->max_slist_size = (cache_ptr)->slist_size;   \
-        if ( (entry_ptr)->size >                                     \
-             ((cache_ptr)->max_size)[(entry_ptr)->type->id] ) {      \
-            ((cache_ptr)->max_size)[(entry_ptr)->type->id]           \
-                 = (entry_ptr)->size;                                \
-        }
-
 #define H5C__UPDATE_STATS_FOR_UNPROTECT(cache_ptr)                   \
         if ( (cache_ptr)->slist_len > (cache_ptr)->max_slist_len )   \
 	    (cache_ptr)->max_slist_len = (cache_ptr)->slist_len;     \
@@ -661,6 +648,31 @@ if ( ( (entry_ptr) == NULL ) ||                                                \
                  = (entry_ptr)->pins;                               \
         }
 
+#define H5C__UPDATE_STATS_FOR_INSERTION(cache_ptr, entry_ptr)            \
+	(((cache_ptr)->insertions)[(entry_ptr)->type->id])++;            \
+	if ( (entry_ptr)->is_pinned ) {                                  \
+	    (((cache_ptr)->pinned_insertions)[(entry_ptr)->type->id])++; \
+	    ((cache_ptr)->pins)[(entry_ptr)->type->id]++;                \
+            (entry_ptr)->pins++;                                         \
+	    if ( (cache_ptr)->pel_len > (cache_ptr)->max_pel_len )       \
+	        (cache_ptr)->max_pel_len = (cache_ptr)->pel_len;         \
+	    if ( (cache_ptr)->pel_size > (cache_ptr)->max_pel_size )     \
+	        (cache_ptr)->max_pel_size = (cache_ptr)->pel_size;       \
+	}                                                                \
+        if ( (cache_ptr)->index_len > (cache_ptr)->max_index_len )       \
+	    (cache_ptr)->max_index_len = (cache_ptr)->index_len;         \
+        if ( (cache_ptr)->index_size > (cache_ptr)->max_index_size )     \
+	    (cache_ptr)->max_index_size = (cache_ptr)->index_size;       \
+        if ( (cache_ptr)->slist_len > (cache_ptr)->max_slist_len )       \
+	    (cache_ptr)->max_slist_len = (cache_ptr)->slist_len;         \
+        if ( (cache_ptr)->slist_size > (cache_ptr)->max_slist_size )     \
+	    (cache_ptr)->max_slist_size = (cache_ptr)->slist_size;       \
+        if ( (entry_ptr)->size >                                         \
+             ((cache_ptr)->max_size)[(entry_ptr)->type->id] ) {          \
+            ((cache_ptr)->max_size)[(entry_ptr)->type->id]               \
+                 = (entry_ptr)->size;                                    \
+        }
+
 #define H5C__UPDATE_STATS_FOR_PROTECT(cache_ptr, entry_ptr, hit)     \
 	if ( hit )                                                   \
             ((cache_ptr)->hits)[(entry_ptr)->type->id]++;            \
@@ -708,6 +720,25 @@ if ( ( (entry_ptr) == NULL ) ||                                                \
 #define H5C__UPDATE_STATS_FOR_EVICTION(cache_ptr, entry_ptr) \
 	(((cache_ptr)->evictions)[(entry_ptr)->type->id])++;
 
+#define H5C__UPDATE_STATS_FOR_INSERTION(cache_ptr, entry_ptr)            \
+	(((cache_ptr)->insertions)[(entry_ptr)->type->id])++;            \
+	if ( (entry_ptr)->is_pinned ) {                                  \
+	    (((cache_ptr)->pinned_insertions)[(entry_ptr)->type->id])++; \
+	    ((cache_ptr)->pins)[(entry_ptr)->type->id]++;                \
+	    if ( (cache_ptr)->pel_len > (cache_ptr)->max_pel_len )       \
+	        (cache_ptr)->max_pel_len = (cache_ptr)->pel_len;         \
+	    if ( (cache_ptr)->pel_size > (cache_ptr)->max_pel_size )     \
+	        (cache_ptr)->max_pel_size = (cache_ptr)->pel_size;       \
+	}                                                                \
+        if ( (cache_ptr)->index_len > (cache_ptr)->max_index_len )       \
+	    (cache_ptr)->max_index_len = (cache_ptr)->index_len;         \
+        if ( (cache_ptr)->index_size > (cache_ptr)->max_index_size )     \
+	    (cache_ptr)->max_index_size = (cache_ptr)->index_size;       \
+        if ( (cache_ptr)->slist_len > (cache_ptr)->max_slist_len )       \
+	    (cache_ptr)->max_slist_len = (cache_ptr)->slist_len;         \
+        if ( (cache_ptr)->slist_size > (cache_ptr)->max_slist_size )     \
+	    (cache_ptr)->max_slist_size = (cache_ptr)->slist_size;
+
 #define H5C__UPDATE_STATS_FOR_PROTECT(cache_ptr, entry_ptr, hit)     \
 	if ( hit )                                                   \
             ((cache_ptr)->hits)[(entry_ptr)->type->id]++;            \
@@ -1572,6 +1603,10 @@ if ( ( (cache_ptr) == NULL ) ||                                          \
  *		This macro should never be called on a pinned entry.
  *		Inserted an assert to verify this.
  *
+ *		JRM - 8/9/06
+ *		Not any more.  We must now allow insertion of pinned 
+ *		entries.  Updated macro to support this.
+ *
  *-------------------------------------------------------------------------
  */
 
@@ -1583,35 +1618,44 @@ if ( ( (cache_ptr) == NULL ) ||                                          \
     HDassert( (cache_ptr)->magic == H5C__H5C_T_MAGIC );                    \
     HDassert( (entry_ptr) );                                               \
     HDassert( !((entry_ptr)->is_protected) );                              \
-    HDassert( !((entry_ptr)->is_pinned) );                                 \
     HDassert( (entry_ptr)->size > 0 );                                     \
                                                                            \
-    /* modified LRU specific code */                                       \
+    if ( (entry_ptr)->is_pinned ) {                                        \
                                                                            \
-    /* insert the entry at the head of the LRU list. */                    \
+        H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->pel_head_ptr,           \
+                         (cache_ptr)->pel_tail_ptr,                        \
+                         (cache_ptr)->pel_len,                             \
+                         (cache_ptr)->pel_size, (fail_val))                \
                                                                            \
-    H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->LRU_head_ptr,               \
-                     (cache_ptr)->LRU_tail_ptr, (cache_ptr)->LRU_list_len, \
-                     (cache_ptr)->LRU_list_size, (fail_val))               \
+    } else {                                                               \
                                                                            \
-    /* insert the entry at the head of the clean or dirty LRU list as      \
-     * appropriate.                                                        \
-     */                                                                    \
+        /* modified LRU specific code */                                   \
                                                                            \
-    if ( entry_ptr->is_dirty ) {                                           \
-        H5C__AUX_DLL_PREPEND((entry_ptr), (cache_ptr)->dLRU_head_ptr,      \
-                             (cache_ptr)->dLRU_tail_ptr,                   \
-                             (cache_ptr)->dLRU_list_len,                   \
-                             (cache_ptr)->dLRU_list_size, (fail_val))      \
-    } else {                                                               \
-        H5C__AUX_DLL_PREPEND((entry_ptr), (cache_ptr)->cLRU_head_ptr,      \
-                             (cache_ptr)->cLRU_tail_ptr,                   \
-                             (cache_ptr)->cLRU_list_len,                   \
-                             (cache_ptr)->cLRU_list_size, (fail_val))      \
-    }                                                                      \
+        /* insert the entry at the head of the LRU list. */                \
+                                                                           \
+        H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->LRU_head_ptr,           \
+                         (cache_ptr)->LRU_tail_ptr,                        \
+			 (cache_ptr)->LRU_list_len,                        \
+                         (cache_ptr)->LRU_list_size, (fail_val))           \
                                                                            \
-    /* End modified LRU specific code. */                                  \
+        /* insert the entry at the head of the clean or dirty LRU list as  \
+         * appropriate.                                                    \
+         */                                                                \
                                                                            \
+        if ( entry_ptr->is_dirty ) {                                       \
+            H5C__AUX_DLL_PREPEND((entry_ptr), (cache_ptr)->dLRU_head_ptr,  \
+                                 (cache_ptr)->dLRU_tail_ptr,               \
+                                 (cache_ptr)->dLRU_list_len,               \
+                                 (cache_ptr)->dLRU_list_size, (fail_val))  \
+        } else {                                                           \
+            H5C__AUX_DLL_PREPEND((entry_ptr), (cache_ptr)->cLRU_head_ptr,  \
+                                 (cache_ptr)->cLRU_tail_ptr,               \
+                                 (cache_ptr)->cLRU_list_len,               \
+                                 (cache_ptr)->cLRU_list_size, (fail_val))  \
+        }                                                                  \
+                                                                           \
+        /* End modified LRU specific code. */                              \
+    }                                                                      \
 }
 
 #else /* H5C_MAINTAIN_CLEAN_AND_DIRTY_LRU_LISTS */
@@ -1622,19 +1666,28 @@ if ( ( (cache_ptr) == NULL ) ||                                          \
     HDassert( (cache_ptr)->magic == H5C__H5C_T_MAGIC );                    \
     HDassert( (entry_ptr) );                                               \
     HDassert( !((entry_ptr)->is_protected) );                              \
-    HDassert( !((entry_ptr)->is_pinned) );                                 \
     HDassert( (entry_ptr)->size > 0 );                                     \
                                                                            \
-    /* modified LRU specific code */                                       \
+    if ( (entry_ptr)->is_pinned ) {                                        \
+                                                                           \
+        H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->pel_head_ptr,           \
+                         (cache_ptr)->pel_tail_ptr,                        \
+                         (cache_ptr)->pel_len,                             \
+                         (cache_ptr)->pel_size, (fail_val))                \
+                                                                           \
+    } else {                                                               \
                                                                            \
-    /* insert the entry at the head of the LRU list. */                    \
+        /* modified LRU specific code */                                   \
                                                                            \
-    H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->LRU_head_ptr,               \
-                     (cache_ptr)->LRU_tail_ptr, (cache_ptr)->LRU_list_len, \
-                     (cache_ptr)->LRU_list_size, (fail_val))               \
+        /* insert the entry at the head of the LRU list. */                \
                                                                            \
-    /* End modified LRU specific code. */                                  \
+        H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->LRU_head_ptr,           \
+                         (cache_ptr)->LRU_tail_ptr,                        \
+			 (cache_ptr)->LRU_list_len,                        \
+                         (cache_ptr)->LRU_list_size, (fail_val))           \
                                                                            \
+        /* End modified LRU specific code. */                              \
+    }                                                                      \
 }
 
 #endif /* H5C_MAINTAIN_CLEAN_AND_DIRTY_LRU_LISTS */
@@ -3908,6 +3961,9 @@ done:
  *		Added initialization for the new dirtied field of the
  *		H5C_cache_entry_t structure.
  *
+ *		JRM -- 8/9/06
+ *		Added code supporting insertion of pinned entries.
+ *
  *-------------------------------------------------------------------------
  */
 
@@ -3924,6 +3980,7 @@ H5C_insert_entry(H5F_t * 	     f,
     herr_t		result;
     herr_t		ret_value = SUCCEED;    /* Return value */
     hbool_t		first_flush = TRUE;
+    hbool_t		insert_pinned;
     hbool_t             set_flush_marker;
     hbool_t		write_permitted = TRUE;
     H5C_cache_entry_t *	entry_ptr;
@@ -3956,6 +4013,7 @@ H5C_insert_entry(H5F_t * 	     f,
 #endif /* H5C_DO_EXTREME_SANITY_CHECKS */
 
     set_flush_marker = ( (flags & H5C__SET_FLUSH_MARKER_FLAG) != 0 );
+    insert_pinned    = ( (flags & H5C__PIN_ENTRY_FLAG) != 0 );
 
     entry_ptr = (H5C_cache_entry_t *)thing;
 
@@ -4092,7 +4150,7 @@ H5C_insert_entry(H5F_t * 	     f,
 
     entry_ptr->is_protected = FALSE;
 
-    entry_ptr->is_pinned = FALSE;
+    entry_ptr->is_pinned = insert_pinned;
 
     H5C__INSERT_IN_INDEX(cache_ptr, entry_ptr, FAIL)
 
@@ -5712,6 +5770,9 @@ done:
  *		JRM -- 3/21/06
  *		Added code supporting the pinned entry related stats.
  *
+ *		JRM -- 8/9/06
+ *		More code supporting pinned entry related stats.
+ *
  *-------------------------------------------------------------------------
  */
 
@@ -5731,6 +5792,7 @@ H5C_stats(H5C_t * cache_ptr,
     int64_t     total_hits = 0;
     int64_t     total_misses = 0;
     int64_t     total_insertions = 0;
+    int64_t     total_pinned_insertions = 0;
     int64_t     total_clears = 0;
     int64_t     total_flushes = 0;
     int64_t     total_evictions = 0;
@@ -5769,20 +5831,21 @@ H5C_stats(H5C_t * cache_ptr,
 
     for ( i = 0; i <= cache_ptr->max_type_id; i++ ) {
 
-        total_hits           += cache_ptr->hits[i];
-        total_misses         += cache_ptr->misses[i];
-        total_insertions     += cache_ptr->insertions[i];
-        total_clears         += cache_ptr->clears[i];
-        total_flushes        += cache_ptr->flushes[i];
-        total_evictions      += cache_ptr->evictions[i];
-        total_renames        += cache_ptr->renames[i];
-        total_size_increases += cache_ptr->size_increases[i];
-        total_size_decreases += cache_ptr->size_decreases[i];
-	total_pins           += cache_ptr->pins[i];
-	total_unpins         += cache_ptr->unpins[i];
-	total_dirty_pins     += cache_ptr->dirty_pins[i];
-	total_pinned_flushes += cache_ptr->pinned_flushes[i];
-	total_pinned_clears  += cache_ptr->pinned_clears[i];
+        total_hits              += cache_ptr->hits[i];
+        total_misses            += cache_ptr->misses[i];
+        total_insertions        += cache_ptr->insertions[i];
+        total_pinned_insertions += cache_ptr->pinned_insertions[i];
+        total_clears            += cache_ptr->clears[i];
+        total_flushes           += cache_ptr->flushes[i];
+        total_evictions         += cache_ptr->evictions[i];
+        total_renames           += cache_ptr->renames[i];
+        total_size_increases    += cache_ptr->size_increases[i];
+        total_size_decreases    += cache_ptr->size_decreases[i];
+	total_pins              += cache_ptr->pins[i];
+	total_unpins            += cache_ptr->unpins[i];
+	total_dirty_pins        += cache_ptr->dirty_pins[i];
+	total_pinned_flushes    += cache_ptr->pinned_flushes[i];
+	total_pinned_clears     += cache_ptr->pinned_clears[i];
 #if H5C_COLLECT_CACHE_ENTRY_STATS
     if ( aggregate_max_accesses < cache_ptr->max_accesses[i] )
         aggregate_max_accesses = cache_ptr->max_accesses[i];
@@ -5911,9 +5974,11 @@ H5C_stats(H5C_t * cache_ptr,
               (long)total_flushes,
               (long)total_evictions);
 
-    HDfprintf(stdout, "%s  Total insertions / renames         = %ld / %ld\n",
+    HDfprintf(stdout, 
+	      "%s  Total insertions(pinned) / renames = %ld(%ld) / %ld\n",
               cache_ptr->prefix,
               (long)total_insertions,
+              (long)total_pinned_insertions,
               (long)total_renames);
 
     HDfprintf(stdout, "%s  Total entry size incrs / decrs     = %ld / %ld\n",
@@ -5986,9 +6051,10 @@ H5C_stats(H5C_t * cache_ptr,
                       (long)(cache_ptr->evictions[i]));
 
             HDfprintf(stdout,
-                      "%s    insertions / renames           = %ld / %ld\n",
+                      "%s    insertions(pinned) / renames   = %ld(%ld) / %ld\n",
                       cache_ptr->prefix,
                       (long)(cache_ptr->insertions[i]),
+                      (long)(cache_ptr->pinned_insertions[i]),
                       (long)(cache_ptr->renames[i]));
 
             HDfprintf(stdout,
@@ -6066,6 +6132,9 @@ done:
  *		JRM - 3/20/06
  *		Updated for pin / unpin related statistics.
  *
+ *		JRM - 8/9/06 
+ *		Further updates for pin related statistics.
+ *
  *-------------------------------------------------------------------------
  */
 
@@ -6085,6 +6154,7 @@ H5C_stats__reset(H5C_t * cache_ptr)
         cache_ptr->hits[i]			= 0;
         cache_ptr->misses[i]			= 0;
         cache_ptr->insertions[i]		= 0;
+        cache_ptr->pinned_insertions[i]		= 0;
         cache_ptr->clears[i]			= 0;
         cache_ptr->flushes[i]			= 0;
         cache_ptr->evictions[i]	 		= 0;
diff --git a/src/H5Cpkg.h b/src/H5Cpkg.h
index 72e775f..7895315 100644
--- a/src/H5Cpkg.h
+++ b/src/H5Cpkg.h
@@ -545,6 +545,11 @@
  *		id equal to the array index has been inserted into the
  *		cache in the current epoch.
  *
+ * pinned_insertions:  Array of int64 of length H5C__MAX_NUM_TYPE_IDS + 1.  
+ * 		The cells are used to record the number of times an entry 
+ * 		with type id equal to the array index has been inserted 
+ * 		pinned into the cache in the current epoch.
+ *
  * clears:      Array of int64 of length H5C__MAX_NUM_TYPE_IDS + 1.  The cells
  *		are used to record the number of times an entry with type
  *		id equal to the array index has been cleared in the current
@@ -788,6 +793,7 @@ struct H5C_t
     int64_t                     hits[H5C__MAX_NUM_TYPE_IDS + 1];
     int64_t                     misses[H5C__MAX_NUM_TYPE_IDS + 1];
     int64_t                     insertions[H5C__MAX_NUM_TYPE_IDS + 1];
+    int64_t                     pinned_insertions[H5C__MAX_NUM_TYPE_IDS + 1];
     int64_t                     clears[H5C__MAX_NUM_TYPE_IDS + 1];
     int64_t                     flushes[H5C__MAX_NUM_TYPE_IDS + 1];
     int64_t                     evictions[H5C__MAX_NUM_TYPE_IDS + 1];
diff --git a/src/H5Cprivate.h b/src/H5Cprivate.h
index ac8851a..63393ec 100644
--- a/src/H5Cprivate.h
+++ b/src/H5Cprivate.h
@@ -60,7 +60,7 @@
  */
 #if H5C_COLLECT_CACHE_STATS
 
-#define H5C_COLLECT_CACHE_ENTRY_STATS	1
+#define H5C_COLLECT_CACHE_ENTRY_STATS	0
 
 #else
 
@@ -749,29 +749,52 @@ typedef struct H5C_auto_size_ctl_t
  * following function calls.  Note that not all flags are applicable
  * to all function calls.  Flags that don't apply to a particular
  * function are ignored in that function.
+ *
+ * These flags apply to all function calls:
+ *
+ * 	H5C__NO_FLAGS_SET (generic "no flags set" for all fcn calls)
+ *
+ *
+ * These flags apply to H5C_insert_entry():
+ *
+ * 	H5C__SET_FLUSH_MARKER_FLAG
+ * 	H5C__PIN_ENTRY_FLAG
+ *
+ * These flags apply to H5C_unprotect():
+ *
+ * 	H5C__SET_FLUSH_MARKER_FLAG
+ * 	H5C__DELETED_FLAG
+ * 	H5C__DIRTIED_FLAG
+ * 	H5C__SIZE_CHANGED_FLAG
+ * 	H5C__PIN_ENTRY_FLAG
+ * 	H5C__UNPIN_ENTRY_FLAG
+ *
+ *
+ * These flags apply to H5C_flush_cache():
+ *
+ * 	H5C__FLUSH_INVALIDATE_FLAG
+ * 	H5C__FLUSH_CLEAR_ONLY_FLAG
+ * 	H5C__FLUSH_MARKED_ENTRIES_FLAG
+ *	H5C__FLUSH_IGNORE_PROTECTED_FLAG (can't use this flag in combination
+ *					  with H5C__FLUSH_INVALIDATE_FLAG)
+ *
+ * These flags apply to H5C_flush_single_entry():
+ *
+ * 	H5C__FLUSH_INVALIDATE_FLAG
+ * 	H5C__FLUSH_CLEAR_ONLY_FLAG
+ * 	H5C__FLUSH_MARKED_ENTRIES_FLAG
  */
 
-/* Generic "no flags set" value for all function calls */
 #define H5C__NO_FLAGS_SET			0x0000
-
-/* These flags apply to H5C_insert_entry() & H5C_unprotect() */
 #define H5C__SET_FLUSH_MARKER_FLAG		0x0001
 #define H5C__DELETED_FLAG			0x0002
-
-/* These flags applies only to H5C_unprotect() */
 #define H5C__DIRTIED_FLAG			0x0004
 #define H5C__SIZE_CHANGED_FLAG			0x0008
 #define H5C__PIN_ENTRY_FLAG			0x0010
 #define H5C__UNPIN_ENTRY_FLAG			0x0020
-
-/* These flags apply to H5C_flush_cache() & H5C_flush_single_entry() */
 #define H5C__FLUSH_INVALIDATE_FLAG		0x0040
 #define H5C__FLUSH_CLEAR_ONLY_FLAG		0x0080
 #define H5C__FLUSH_MARKED_ENTRIES_FLAG		0x0100
-
-/* This flag applies to H5C_flush_cache() only.  It is an error to use
- * it in combination with the H5C__FLUSH_INVALIDATE_FLAG
- */
 #define H5C__FLUSH_IGNORE_PROTECTED_FLAG	0x0200
 
 
diff --git a/test/cache.c b/test/cache.c
index 98f68d5..440b5e3 100644
--- a/test/cache.c
+++ b/test/cache.c
@@ -34,6 +34,7 @@ static void smoke_check_6(void);
 static void smoke_check_7(void);
 static void smoke_check_8(void);
 static void write_permitted_check(void);
+static void check_insert_entry(void);
 static void check_flush_cache(void);
 static void check_flush_cache__empty_cache(H5C_t * cache_ptr);
 static void check_flush_cache__multi_entry(H5C_t * cache_ptr);
@@ -2000,6 +2001,308 @@ write_permitted_check(void)
 
 
 /*-------------------------------------------------------------------------
+ * Function:	check_insert_entry()
+ *
+ * Purpose:	Verify that H5C_insert_entry behaves as expected.
+ *		Test the behaviour with different flags.
+ *
+ *		This test was added primarily to test basic insert
+ *		pinned entry functionallity, but I through in explicit
+ *		tests for other functionallity that is tested implicitly
+ *		elsewhere.
+ *
+ * Return:	void
+ *
+ * Programmer:	John Mainzer
+ *              8/10/06
+ *
+ * Modifications:
+ *
+ *-------------------------------------------------------------------------
+ */
+
+static void
+check_insert_entry(void)
+{
+    const char *               fcn_name = "check_insert_entry";
+    int                        entry_type = PICO_ENTRY_TYPE;
+    int                        i;
+    herr_t                     result;
+    hbool_t                    in_cache;
+    hbool_t                    is_dirty;
+    hbool_t                    is_protected;
+    hbool_t                    is_pinned;
+    size_t                     entry_size;
+    H5C_t *                    cache_ptr = NULL;
+    test_entry_t *             base_addr;
+    test_entry_t *             entry_ptr;
+    struct H5C_cache_entry_t * search_ptr;
+
+
+    TESTING("H5C_insert_entry() functionality");
+
+    pass = TRUE;
+
+    /* Allocate a cache, and insert entries into it using all 
+     * combinations of flags.  Verify that the entries are inserted,
+     * and that the flags have the desired effects.
+     *
+     * Note that the dirty parameter in insert_entry is no longer
+     * used, as we have decided that all inserted entries are 
+     * dirty by definition. (Which sounds very reasonable, but didn't
+     * used to be the case.)
+     */
+
+    if ( pass ) {
+
+        reset_entries();
+
+        cache_ptr = setup_cache((size_t)(2 * 1024 * 1024),
+                                (size_t)(1 * 1024 * 1024));
+    }
+
+    if ( pass ) {
+
+        insert_entry(cache_ptr, entry_type, 0, TRUE, H5C__NO_FLAGS_SET);
+        insert_entry(cache_ptr, entry_type, 1, TRUE, 
+                     H5C__SET_FLUSH_MARKER_FLAG);
+        insert_entry(cache_ptr, entry_type, 2, TRUE, H5C__PIN_ENTRY_FLAG);
+        insert_entry(cache_ptr, entry_type, 3, TRUE, 
+		     (H5C__SET_FLUSH_MARKER_FLAG | H5C__PIN_ENTRY_FLAG));
+    }
+
+
+    /* Verify that the entries are inserted as desired. */
+
+    i = 0;
+    base_addr = entries[0];
+    while ( ( pass ) && ( i < 4 ) )
+    {
+	entry_ptr = &(base_addr[i]);
+
+	/* Start by checking everything we can via H5C_get_entry_status() */
+
+	result = H5C_get_entry_status(cache_ptr, entry_ptr->addr, &entry_size,
+			              &in_cache, &is_dirty, &is_protected, 
+				      &is_pinned);
+
+        if ( result < 0 ) {
+
+            pass = FALSE;
+            failure_mssg = "H5AC_get_entry_status() reports failure.";
+        }
+
+	if ( pass ) { 
+
+	    /* check the universals */
+	    if ( ( ! in_cache ) || ( ! is_dirty ) || ( is_protected ) || 
+                 ( entry_size != entry_sizes[entry_type] ) ) {
+
+                pass = FALSE;
+                failure_mssg = "Unexpected insert results 1.";
+            }
+	}
+
+	if ( pass ) {
+
+            /* verify that the pinned flag got set correctly */
+	    if ( ( i == 2 ) || ( i == 3 ) ) {
+
+		if ( ! is_pinned ) {
+
+                    pass = FALSE;
+                    failure_mssg = "Unexpected insert results 2.";
+		}
+	    } else if ( is_pinned ) {
+
+                pass = FALSE;
+                failure_mssg = "Unexpected insert results 3.";
+
+	    } else if ( is_pinned != ((entry_ptr->header).is_pinned) ) {
+
+                pass = FALSE;
+                failure_mssg = "Unexpected insert results 4.";
+            }
+	}
+
+	/* Thats all we can get from H5AC_get_entry_status().
+	 * Now start looking at the cache data structures directly.
+	 */
+
+	if ( pass ) {
+
+            /* Verify that the flush marker got set correctly */
+	    if ( ( i == 1 ) || ( i == 3 ) ) {
+
+		if ( ! ((entry_ptr->header).flush_marker) ) {
+
+                    pass = FALSE;
+                    failure_mssg = "Unexpected insert results 5.";
+		}
+	    } else if ( (entry_ptr->header).flush_marker ) {
+
+                pass = FALSE;
+                failure_mssg = "Unexpected insert results 6.";
+	    }
+	}
+
+	if ( pass ) {
+
+	    /* Verify that pinned entries are in the pinned entry list */
+	    if ( (entry_ptr->header).is_pinned ) {
+
+		search_ptr = cache_ptr->pel_head_ptr;
+
+		while ( ( search_ptr != NULL ) &&
+			( search_ptr != 
+			  (struct H5C_cache_entry_t *)entry_ptr ) )
+		{
+		    search_ptr = search_ptr->next;
+		}
+
+		if ( search_ptr == NULL ) {
+
+                    pass = FALSE;
+                    failure_mssg = "Unexpected insert results 7.";
+		}
+	    }
+	}
+
+	if ( pass ) {
+
+	    /* Verify that unpinned entries are in the LRU list */
+	    if ( ! ((entry_ptr->header).is_pinned) ) {
+
+		search_ptr = cache_ptr->LRU_head_ptr;
+
+		while ( ( search_ptr != NULL ) &&
+			( search_ptr != 
+			  (struct H5C_cache_entry_t *)entry_ptr ) )
+		{
+		    search_ptr = search_ptr->next;
+		}
+
+		if ( search_ptr == NULL ) {
+
+                    pass = FALSE;
+                    failure_mssg = "Unexpected insert results 8.";
+		}
+	    }
+	}
+
+#if H5C_MAINTAIN_CLEAN_AND_DIRTY_LRU_LISTS
+	if ( pass ) {
+
+	    /* Verify that unpinned entries are in the dirty LRU list */
+	    if ( ! ((entry_ptr->header).is_pinned) ) {
+
+		search_ptr = cache_ptr->dLRU_head_ptr;
+
+		while ( ( search_ptr != NULL ) &&
+			( search_ptr != 
+			  (struct H5C_cache_entry_t *)entry_ptr ) )
+		{
+		    search_ptr = search_ptr->aux_next;
+		}
+
+		if ( search_ptr == NULL ) {
+
+                    pass = FALSE;
+                    failure_mssg = "Unexpected insert results 9.";
+		}
+	    }
+	}
+#endif /* H5C_MAINTAIN_CLEAN_AND_DIRTY_LRU_LISTS */
+
+	i++;
+
+    } /* while */
+
+
+    /* So much for looking at the individual entries.  Now verify 
+     * that the various counts and sized in the cache header are 
+     * as expected.
+     */
+
+    if ( pass ) {
+
+	if ( ( cache_ptr->index_len != 4 ) ||
+	     ( cache_ptr->index_size != 4 * entry_sizes[entry_type] ) ||
+	     ( cache_ptr->slist_len != 4 ) ||
+	     ( cache_ptr->slist_size != 4 * entry_sizes[entry_type] ) ||
+	     ( cache_ptr->pl_len != 0 ) ||
+	     ( cache_ptr->pl_size != (size_t)0 ) ||
+	     ( cache_ptr->pel_len != 2 ) ||
+	     ( cache_ptr->pel_size != 2 * entry_sizes[entry_type] ) ||
+	     ( cache_ptr->LRU_list_len != 2 ) ||
+	     ( cache_ptr->LRU_list_size != 2 * entry_sizes[entry_type] ) ||
+#if H5C_MAINTAIN_CLEAN_AND_DIRTY_LRU_LISTS
+	     ( cache_ptr->dLRU_list_len != 2 ) ||
+	     ( cache_ptr->dLRU_list_size != 2 * entry_sizes[entry_type] ) ||
+#endif /* H5C_MAINTAIN_CLEAN_AND_DIRTY_LRU_LISTS */
+	     ( cache_ptr->cLRU_list_len != 0 ) ||
+	     ( cache_ptr->cLRU_list_size != (size_t)0 ) ) {
+
+            pass = FALSE;
+            failure_mssg = "Unexpected insert results 10.";
+	}
+    }
+
+
+    /* Finally, if stats collection is enabled, verify that the expected
+     * stats are collected.
+     */
+#if H5C_COLLECT_CACHE_STATS
+    if ( pass ) {
+
+	if ( ( cache_ptr->insertions[entry_type] != 4 ) ||
+	     ( cache_ptr->pinned_insertions[entry_type] != 2 ) ||
+	     ( cache_ptr->pins[entry_type] != 2 ) ||
+	     ( cache_ptr->unpins[entry_type] != 0 ) ||
+             ( cache_ptr->dirty_pins[entry_type] != 0 ) ||
+	     ( cache_ptr->max_index_len != 4 ) ||
+	     ( cache_ptr->max_index_size != 4 * entry_sizes[entry_type] ) ||
+	     ( cache_ptr->max_slist_len != 4 ) ||
+	     ( cache_ptr->max_slist_size != 4 * entry_sizes[entry_type] ) ||
+	     ( cache_ptr->max_pl_len != 0 ) ||
+	     ( cache_ptr->max_pl_size != (size_t)0 ) ||
+	     ( cache_ptr->max_pel_len != 2 ) ||
+	     ( cache_ptr->max_pel_size != 2 * entry_sizes[entry_type] ) ) {
+
+            pass = FALSE;
+            failure_mssg = "Unexpected insert results 11.";
+	}
+    }
+#endif /* H5C_COLLECT_CACHE_STATS */
+
+
+    /* Unpin the pinned entries so we can take down the cache cleanly. */
+
+    if ( pass ) {
+
+        unpin_entry(cache_ptr, entry_type, 2);
+	unpin_entry(cache_ptr, entry_type, 3);
+    }
+
+    if ( pass ) {
+
+        takedown_cache(cache_ptr, FALSE, FALSE);
+    }
+
+    if ( pass ) { PASSED(); } else { H5_FAILED(); }
+
+    if ( ! pass ) {
+
+        HDfprintf(stdout, "%s(): failure_mssg = \"%s\".\n",
+                  fcn_name, failure_mssg);
+    }
+
+    return;
+
+} /* check_insert_entry() */
+
+
+/*-------------------------------------------------------------------------
  * Function:	check_flush_cache()
  *
  * Purpose:	Verify that flush_cache behaves as expected.  In particular,
@@ -5690,6 +5993,7 @@ check_flush_cache__single_entry(H5C_t * cache_ptr)
         );
     }
 
+
     /* Now run single entry tests for pinned entries.  Test all combinations
      * of:
      *
@@ -18448,6 +18752,7 @@ main(void)
 #endif
 #if 1
     write_permitted_check();
+    check_insert_entry();
     check_flush_cache();
     check_get_entry_status();
     check_expunge_entry();
diff --git a/test/cache_common.c b/test/cache_common.c
index 7e04d37..a9a3f55 100644
--- a/test/cache_common.c
+++ b/test/cache_common.c
@@ -1600,6 +1600,10 @@ flush_cache(H5C_t * cache_ptr,
  *		Added code to initialize the new cache_ptr field of the
  *		test_entry_t structure.
  *
+ *		JRM -- 8/10/06
+ *		Updated to reflect the fact that entries can now be
+ *		inserted pinned.
+ *
  *-------------------------------------------------------------------------
  */
 
@@ -1611,6 +1615,7 @@ insert_entry(H5C_t * cache_ptr,
              unsigned int flags)
 {
     herr_t result;
+    hbool_t insert_pinned;
     test_entry_t * base_addr;
     test_entry_t * entry_ptr;
 
@@ -1628,6 +1633,8 @@ insert_entry(H5C_t * cache_ptr,
         HDassert( entry_ptr == entry_ptr->self );
         HDassert( !(entry_ptr->is_protected) );
 
+	insert_pinned = ((flags & H5C__PIN_ENTRY_FLAG) != 0 );
+
 	entry_ptr->is_dirty = TRUE;
 
         result = H5C_insert_entry(NULL, -1, -1, cache_ptr, &(types[type]),
@@ -1663,6 +1670,17 @@ insert_entry(H5C_t * cache_ptr,
 
         entry_ptr->cache_ptr = cache_ptr;
 
+	if ( insert_pinned ) {
+
+	    HDassert( entry_ptr->header.is_pinned );
+	    entry_ptr->is_pinned = TRUE;
+
+	} else {
+
+	    HDassert( ! ( entry_ptr->header.is_pinned ) );
+	    entry_ptr->is_pinned = FALSE;
+
+	}
         HDassert( entry_ptr->header.is_dirty );
         HDassert( ((entry_ptr->header).type)->id == type );
     }