[svn-r27237] Description:

    Merge v3 metadata cache changes to trunk.  Yay! :-)

Tested on:
    MacOSX/64 10.10.3 (amazon) w/serial & parallel
    Linux/32 2.6.x (jam) w/serial & parallel
    (daily tested on branch)

1 files changed, 985 insertions, 135 deletions

diff --git a/src/H5Cprivate.h b/src/H5Cprivate.h
index 3413381..a9ffb70 100644
--- a/src/H5Cprivate.h
+++ b/src/H5Cprivate.h
@@ -40,9 +40,30 @@
 /* Library Private Macros */
 /**************************/
 
-#define H5C_DO_SANITY_CHECKS		0
+#ifndef NDEBUG
+#define H5C_DO_SANITY_CHECKS		1
+#define H5C_DO_SLIST_SANITY_CHECKS	0
 #define H5C_DO_TAGGING_SANITY_CHECKS	1
 #define H5C_DO_EXTREME_SANITY_CHECKS	0
+#else /* NDEBUG */
+/* With rare execptions, the following defines should be set 
+ * to 0 if NDEBUG is defined 
+ */
+#define H5C_DO_SANITY_CHECKS		0
+#define H5C_DO_SLIST_SANITY_CHECKS	0
+#define H5C_DO_TAGGING_SANITY_CHECKS	0
+#define H5C_DO_EXTREME_SANITY_CHECKS	0
+#endif /* NDEBUG */
+
+/* Note: The memory sanity checks aren't going to work until I/O filters are
+ *      changed to call a particular alloc/free routine for their buffers,
+ *      because the H5AC__SERIALIZE_RESIZED_FLAG set by the fractal heap
+ *      direct block serialize callback calls H5Z_pipeline().  When the I/O
+ *      filters are changed, then we should implement "cache image alloc/free"
+ *      routines that the fractal heap direct block (and global heap) serialize
+ *      calls can use when resizing (and re-allocating) their image in the
+ *      cache. -QAK */
+#define H5C_DO_MEMORY_SANITY_CHECKS	0
 
 /* This sanity checking constant was picked out of the air.  Increase
  * or decrease it if appropriate.  Its purposes is to detect corrupt
@@ -53,9 +74,15 @@
 #define H5C_MAX_ENTRY_SIZE		((size_t)(32 * 1024 * 1024))
 
 /* H5C_COLLECT_CACHE_STATS controls overall collection of statistics
- * on cache activity.  In general, this #define should be set to 0.
+ * on cache activity.  In general, this #define should be set to 1 in
+ * debug mode, and 0 in production mode..
  */
+
+#ifndef NDEBUG
+#define H5C_COLLECT_CACHE_STATS	1
+#else /* NDEBUG */
 #define H5C_COLLECT_CACHE_STATS	0
+#endif /* NDEBUG */
 
 /* H5C_COLLECT_CACHE_ENTRY_STATS controls collection of statistics
  * in individual cache entries.
@@ -82,10 +109,20 @@
 #define H5C_MAINTAIN_CLEAN_AND_DIRTY_LRU_LISTS  0
 #endif /* H5_HAVE_PARALLEL */
 
-/* Flags returned from the 'flush' callback */
-#define H5C_CALLBACK__NO_FLAGS_SET		0x0
-#define H5C_CALLBACK__SIZE_CHANGED_FLAG		0x1
-#define H5C_CALLBACK__MOVED_FLAG		0x2
+/* Flags for cache client class behavior */
+#define H5C__CLASS_NO_FLAGS_SET			((unsigned)0x0)
+#define H5C__CLASS_SPECULATIVE_LOAD_FLAG	((unsigned)0x1)
+#define H5C__CLASS_COMPRESSED_FLAG		((unsigned)0x2)
+/* The following flags may only appear in test code */
+#define H5C__CLASS_NO_IO_FLAG			((unsigned)0x4)
+#define H5C__CLASS_SKIP_READS			((unsigned)0x8)
+#define H5C__CLASS_SKIP_WRITES			((unsigned)0x10)
+
+/* Flags for pre-serialize callback */
+#define H5C__SERIALIZE_NO_FLAGS_SET	((unsigned)0)
+#define H5C__SERIALIZE_RESIZED_FLAG	((unsigned)0x1)
+#define H5C__SERIALIZE_MOVED_FLAG	((unsigned)0x2)
+#define H5C__SERIALIZE_COMPRESSED_FLAG  ((unsigned)0x4)
 
 /* Upper and lower limits on cache size.  These limits are picked
  * out of a hat -- you should be able to change them as necessary.
@@ -112,11 +149,9 @@
  */
 #define H5C__NUM_FLUSH_DEP_HEIGHTS            6
 
-#ifndef NDEBUG
 /* Values for cache entry magic field */
 #define H5C__H5C_CACHE_ENTRY_T_MAGIC		0x005CAC0A
 #define H5C__H5C_CACHE_ENTRY_T_BAD_MAGIC	0xDeadBeef
-#endif /* NDEBUG */
 
 /* Cache configuration validation definitions */
 #define H5C_RESIZE_CFG__VALIDATE_GENERAL        0x1
@@ -169,9 +204,13 @@
  * These flags apply to H5C_insert_entry():
  * 	H5C__SET_FLUSH_MARKER_FLAG
  * 	H5C__PIN_ENTRY_FLAG
+ *	H5C__FLUSH_LAST_FLAG		; super block only
+ *	H5C__FLUSH_COLLECTIVELY_FLAG	; super block only
  *
  * These flags apply to H5C_protect()
  * 	H5C__READ_ONLY_FLAG
+ *	H5C__FLUSH_LAST_FLAG		; super block only 
+ *	H5C__FLUSH_COLLECTIVELY_FLAG	; super block only
  *
  * These flags apply to H5C_unprotect():
  * 	H5C__SET_FLUSH_MARKER_FLAG
@@ -223,63 +262,842 @@
 typedef struct H5C_t H5C_t;
 
 
-/*
- * Class methods pertaining to caching.	 Each type of cached object will
- * have a constant variable with permanent life-span that describes how
- * to cache the object.	 That variable will be of type H5C_class_t and
- * have the following required fields...
+/***************************************************************************
+ *
+ * Struct H5C_class_t
+ *
+ * Instances of H5C_class_t are used to specify the callback functions
+ * used by the metadata cache for each class of metadata cache entry.
+ * The fields of the structure are discussed below:
+ *
+ * id:	Integer field containing the unique ID of the class of metadata
+ * 	cache entries.
+ *
+ * name: Pointer to a string containing the name of the class of metadata
+ * 	cache entries.
+ *
+ * mem_type:  Instance of H5FD_mem_t, that is used to supply the
+ * 	mem type passed into H5F_block_read().
+ *
+ * flags:  Flags indicating class-specific behavior.
+ *
+ *	Whoever created the flags field neglected to document the meanings 
+ *      of the flags he created.  Hence the following discussion of the 
+ *	H5C__CLASS_SPECULATIVE_LOAD_FLAG and (to a lesser extent) 
+ *	H5C__CLASS_COMPRESSED_FLAG should be viewed with suspicion, 
+ *	as the meanings are divined from the source code, and thus may be 
+ *	inaccurate.  Please correct any errors you find.
+ *
+ *	Possible flags are:
+ *
+ *	H5C__CLASS_NO_FLAGS_SET: No special processing.
+ *
+ *	H5C__CLASS_SPECULATIVE_LOAD_FLAG: This flag appears to be used
+ *		only in H5C_load_entry().  When it is set, entries are 
+ *		permitted to change their sizes on the first attempt 
+ *		to load.  
+ *
+ *		If the new size is larger than the old, the read buffer
+ *		is reallocated to the new size, loaded from file, and the 
+ *		deserialize routine is called a second time on the 
+ *		new buffer.  The entry returned by the first call to 
+ *		the deserialize routine is discarded (via the free_icr
+ *		call) after the new size is retrieved (via the image_len
+ *		call).  Note that the new size is used as the size of the 
+ *		entry in the cache.
+ *
+ *		If the new size is smaller than the old, no new loads 
+ *		or desearializes are performed, but the new size becomes
+ *		the size of the entry in the cache.
+ *
+ *		When this flag is set, an attempt to read past the 
+ *		end of file is pemitted.  In this case, if the size 
+ *		returned get_load_size callback would result in a 
+ *		read past the end of file, the size is trunkated to 
+ *		avoid this, and processing proceeds as normal.
  *
- * LOAD:	Loads an object from disk to memory.  The function
- *		should allocate some data structure and return it.
+ *	H5C__CLASS_COMPRESSED_FLAG: This flags indicates that the entry 
+ *		may be compressed -- i.e. its on disk image is run through 
+ *		filters on the way to and from disk.  Thus the uncompressed 
+ *		(or unfiltered) size of the entry may be different from the 
+ *		size of the entry in file.  
  *
- * FLUSH:	Writes some data structure back to disk.  It would be
- *		wise for the data structure to include dirty flags to
- *		indicate whether it really needs to be written.	 This
- *		function is also responsible for freeing memory allocated
- *		by the LOAD method if the DEST argument is non-zero (by
- *              calling the DEST method).
+ *		This has the following implications:
  *
- * DEST:	Just frees memory allocated by the LOAD method.
+ *		On load, uncompressed size and load size may be different.  
+ *		Presumably, load size will be smaller than uncompressed 
+ *		size, but there is no requirement for this in the code 
+ *		(but note that I have inserted an assertion to this effect, 
+ *		which has not been triggered to date).
  *
- * CLEAR:	Just marks object as non-dirty.
+ *		On insertion, compressed (AKA filtered, AKA on disk) size 
+ *		is unknown, as the entry has yet to be run through filters.
+ *		Compressed size is computed whenever the entry is 
+ *		written (or the image is updated -- not relevant until 
+ *		journaling is brought back).
  *
- * NOTIFY:	Notify client that an action on an entry has taken/will take
- *              place
+ *		On dirty (of a clean entry), compressed (AKA filtered, 
+ *		AKA on disk) size becomes unknown.  Thus, compressed size
+ *		must be computed by the pre-serialize callback before the 
+ *		entry may be written.  
  *
- * SIZE:	Report the size (on disk) of the specified cache object.
- *		Note that the space allocated on disk may not be contiguous.
- */
+ *		Once the compressed size becomes unknown, it remains so 
+ *		until the on disk image is constructed.  
+ *
+ *		Observe that the cache needs to know the size of the entry
+ *		for space allocation purposes.  Since the compressed size 
+ *		can change or become unknown, it uses the uncompressed
+ *		size which may change, but which should always be known.  
+ *		The compressed size is used only for journaling and disk I/O.
+ *
+ *		While there is no logical reason why they could not be 
+ *		combined, due to absence of need and for simplicity of code, 
+ *		the cache does not permit both the the 
+ *		H5C__CLASS_COMPRESSED_FLAG and the 
+ *		H5C__CLASS_SPECULATIVE_LOAD_FLAG to be set in the same 
+ *		instance of H5C_class_t.
+ *
+ *      The following flags may only appear in test code.
+ *
+ *	H5C__CLASS_NO_IO_FLAG:  This flag is intended only for use in test 
+ *		code.  When it is set, any attempt to load an entry of 
+ *		the type with this flag set will trigger an assertion 
+ *		failure, and any flush of an entry with this flag set 
+ *		will not result in any write to file.
+ *
+ *	H5C__CLASS_SKIP_READS: This flags is intended only for use in test
+ *		code.  When it is set, reads on load will be skipped,
+ *		and an uninitialize buffer will be passed to the 
+ *		deserialize function.
+ *
+ *	H5C__CLASS_SKIP_WRITES: This flags is intended only for use in test
+ *		code.  When it is set, writes of buffers prepared by the 
+ *		serialize callback will be skipped.
+ *
+ * GET_LOAD_SIZE: Pointer to the 'get load size' function.
+ *
+ * 	This function must be able to determine the size of the disk image of
+ *      a metadata cache entry, given the 'udata' that will be passed to the
+ *      'deserialize' callback.
+ *
+ *	Note that if either the H5C__CLASS_SPECULATIVE_LOAD_FLAG or
+ *	the H5C__CLASS_COMPRESSED_FLAG is set, the disk image size 
+ *	returned by this callback is either a first guess (if the 
+ *	H5C__CLASS_SPECULATIVE_LOAD_FLAG is set) or (if the
+ *      H5C__CLASS_COMPRESSED_FLAG is set), the exact on disk size 
+ *	of the entry whether it has been run through filters or not.
+ *	In all other cases, the value returned should be the correct 
+ *	uncompressed size of the entry.
+ *
+ *	The typedef for the deserialize callback is as follows:
+ *
+ * 	   typedef herr_t (*H5C_get_load_size_func_t)(void *udata_ptr,
+ * 	                                           size_t *image_len_ptr);
+ *
+ *	The parameters of the deserialize callback are as follows:
+ *
+ *	udata_ptr: Pointer to user data provided in the protect call, which
+ *         	will also be passed through to the deserialize callback.
+ *
+ *	image_len_ptr: Pointer to the location in which the length in bytes 
+ *		of the in file image to be deserialized is to be returned.
+ *
+ *              This value is used by the cache to determine the size of
+ *              the disk image for the metadata, in order to read the disk
+ *              image from the file.
+ *
+ *	Processing in the get_load_size function should proceed as follows:
+ *
+ *	If successful, the function will place the length of the on disk
+ *	image associated with supplied user data in *image_len_ptr, and 
+ *	then return SUCCEED.
+ *
+ *	On failure, the function must return FAIL and push error information
+ *	onto the error stack with the error API routines, without modifying
+ *      the value pointed to by the image_len_ptr.
+ *
+ *
+ * DESERIALIZE: Pointer to the deserialize function.
+ *
+ * 	This function must be able to read a buffer containing the on disk 
+ *	image of a metadata cache entry, allocate and load the equivalent 
+ *	in core representation, and return a pointer to that representation.
+ *
+ *	The typedef for the deserialize callback is as follows:
+ *
+ * 	   typedef void *(*H5C_deserialize_func_t)(const void * image_ptr,
+ * 	                                           size_t len,
+ *                                                 void * udata_ptr,
+ *                                                 boolean * dirty_ptr);
+ *
+ *	The parameters of the deserialize callback are as follows:
+ *
+ *	image_ptr: Pointer to a buffer of length len containing the
+ *		contents of the file starting at addr and continuing
+ *		for len bytes.
+ *
+ *	len:    Length in bytes of the in file image to be deserialized.
+ *
+ *              This parameter is supplied mainly for sanity checking.
+ *              Sanity checks should be performed when compiled in debug
+ *              mode, but the parameter may be unused when compiled in
+ *              production mode.
+ *
+ *	udata_ptr: Pointer to user data provided in the protect call, which
+ *         	must be passed through to the deserialize callback.
+ *
+ *      dirty_ptr:  Pointer to boolean which the deserialize function
+ *      	must use to mark the entry dirty if it has to modify
+ *      	the entry to clean up file corruption left over from
+ *      	an old bug in the HDF5 library.
+ *
+ *	Processing in the deserialize function should proceed as follows:
+ *
+ *      If the image contains valid data, and is of the correct length,
+ *      the deserialize function must allocate space for an in core
+ *      representation of that data, load the contents of the image into
+ *      the space allocated for the in core representation, and return
+ *      a pointer to the in core representation.  Observe that an
+ *      instance of H5C_cache_entry_t must be the first item in this
+ *      representation.  The cache will initialize it after the callback
+ *      returns.
+ *
+ *      Note that the structure of the in core representation is otherwise
+ *      up to the cache client.  All that is required is that the pointer
+ *      returned be sufficient for the clients purposes when it is returned
+ *      on a protect call.
+ *
+ *      If the deserialize function has to clean up file corruption
+ *      left over from an old bug in the HDF5 library, it must set
+ *      *dirty_ptr to TRUE.  If it doesn't, no action is needed as
+ *      *dirty_ptr will be set to FALSE before the deserialize call.
+ *
+ *      If the operation fails for any reason (i.e. bad data in buffer, bad
+ *      buffer length, malloc failure, etc.) the function must return NULL and
+ *      push error information on the error stack with the error API routines.
+ *
+ *	Exceptions to the above:
+ *
+ *	If the H5C__CLASS_SPECULATIVE_LOAD_FLAG is set, the buffer supplied
+ *	to the function need not be currect on the first invocation of the 
+ *	callback in any single attempt to load the entry.
+ *
+ *	In this case, if the buffer is larger than necessary, the function
+ *	should load the entry as described above and not flag an error due
+ *	to the oversized buffer.  The cache will correct its mis-apprehension
+ *	of the entry size with a subsequent call to the image_len callback.
+ *
+ *	If the buffer is too small, and this is the first deserialize call
+ *	in the entry load operation, the function should not flag an error.
+ *	Instead, it must compute the correct size of the entry, allocate an
+ *	in core representation and initialize it to the extent that an 
+ *	immediate call to the image len callback will return the correct 
+ *	image size.
+ *
+ *	In this case, when the deserialize callback returns, the cache will
+ *	call the image length callback, realize that the supplied buffer was
+ *	too small, discard the returned in core representation, allocate
+ *	and load a new buffer of the correct size from file, and then call
+ *	the deserialize callback again.
+ *
+ *	If the H5C__CLASS_COMPRESSED_FLAG is set, exceptions are as per the
+ *	H5C__CLASS_SPECULATIVE_LOAD_FLAG, save that only oversized buffers
+ *	are permitted.
+ *
+ *
+ * IMAGE_LEN: Pointer to the image length callback.
+ *
+ *	This callback exists primarily to support 
+ *	H5C__CLASS_SPECULATIVE_LOAD_FLAG and H5C__CLASS_COMPRESSED_FLAG 
+ *	discussed above, although it is also used to obtain the size of 
+ *	newly inserted entries.
+ *
+ *	In the case of the H5C__CLASS_SPECULATIVE_LOAD_FLAG, it is used to
+ *	allow the client to change the size of an entry in the deserialize
+ *	callback.
+ *
+ *	For the H5C__CLASS_COMPRESSED_FLAG, it is used to allow the client
+ *	to indicate whether the entry is compressed (i.e. whether entries
+ *	are run through filters) and if so, to report both the uncompressed 
+ *	and the compressed entry size (i.e. the actual on disk size after
+ *	the entry has been run through filters) if that value is known.
+ *
+ *	The callback is also used in H5C_insert_entry() to obtain the 
+ *	size of the newly inserted entry.
+ *
+ *      The typedef for the image_len callback is as follows:
+ *
+ *      typedef herr_t (*H5C_image_len_func_t)(void *thing,
+ *                                           size_t *image_len_ptr,
+ *                                           hbool_t *compressed_ptr,
+ *                                           size_t *compressed_image_len_ptr);
+ *
+ * 	The parameters of the image_len callback are as follows:
+ *
+ *	thing:  Pointer to the in core representation of the entry.
+ *
+ *	image_len_ptr: Pointer to size_t in which the callback will return
+ *		the length (in bytes) of the cache entry.
+ *
+ *		If the H5C__CLASS_COMPRESSED_FLAG is not set in the 
+ *		associated instance of H5C_class_t, or if the flag is 
+ *		set, and the callback sets *compressed_ptr to FALSE,
+ *		this size is the actual size of the entry on disk.
+ *
+ *		Otherwise, this size is the uncompressed size of the 
+ *		entry -- which the cache will use for all purposes OTHER
+ *		than journal writes and disk I/O.
+ *
+ *	compressed_ptr: Pointer to a boolean flag indicating whether 
+ *		the cache entry will be compressed / uncompressed on 
+ *		disk writes / reads.
+ *
+ *		If the H5C__CLASS_COMPRESSED_FLAG is not set in the
+ *              associated instance of H5C_class_t, *compressed_ptr 
+ *		must be set to FALSE.
+ *
+ *		If the H5C__CLASS_COMPRESSED_FLAG is set in the
+ *              associated instance of H5C_class_t, and filters are 
+ *		not enabled, *compressed_ptr must be set to FALSE.
+ *
+ *		If the H5C__CLASS_COMPRESSED_FLAG is set in the
+ *              associated instance of H5C_class_t, and filters are
+ *		enabled, the callback must set *compressed_ptr to TRUE.
+ *
+ *		Note that *compressed_ptr will always be set to FALSE 
+ *		by the caller prior to invocation of the callback.  Thus 
+ *		callbacks for clients that don't set the 
+ *		H5C__CLASS_COMPRESSED_FLAG can ignore this parameter.
+ *
+ *	compressed_image_len_ptr: Pointer to size_t in which the callback 
+ *		may return the length (in bytes) of the compressed on 
+ *		disk image of the entry, or the uncompressed size if the
+ *		compressed size has not yet been calculated.
+ *
+ *		Since computing the compressed image len is expensive, 
+ *		the callback should only report the most recently computed
+ *		value -- which will typically be incorrect if the entry
+ *		is dirty.
+ *
+ *		If *compressed_ptr is set to FALSE, *compressed_image_len_ptr
+ *		should be set to zero.  However, as *compressed_image_len_ptr
+ *		will be initialize to zero prior to the call, the callback 
+ *		need not modify it if the H5C__CLASS_COMPRESSED_FLAG is 
+ *		not set.
+ *
+ *	If the H5C__CLASS_COMPRESSED_FLAG is not set in the associated 
+ *	instance of H5C_class_t, processing in the image_len function 
+ *	should proceed as follows:
+ *
+ *	If successful, the function will place the length of the on disk
+ *	image associated with the in core representation provided in the
+ *	thing parameter in *image_len_ptr, and then return SUCCEED.  Since
+ *	*compressed_ptr and *compressed_image_len_ptr will be initialized to 
+ *	FALSE and zero respectively before the call, the callback need not
+ *	modify these values, and may declare the associated parameters as 
+ *	UNUSED.
+ *
+ *	If the H5C__CLASS_COMPRESSED_FLAG is set in the associated 
+ *      instance of H5C_class_t, processing in the image_len function 
+ *      should proceed as follows:
+ *
+ *	If successful, the function will place the uncompressed length of 
+ *	the on disk image associated with the in core representation 
+ *	provided in the thing parameter in *image_len_ptr.  If filters 
+ *	are not enabled for the entry, it will set *compressed_ptr to FALSE,
+ *      and *compressed_image_len_ptr to zero.  If filters are enabled, 
+ *	it will set *compressed_ptr to TRUE.  In this case, it must set 
+ *	*compressed_image_len_ptr equal to the last computed compressed
+ *	if the compressed size, or to the uncompressed size if that value
+ *	is yet to be computed.  In all cases, it will return SUCCEED if 
+ *	successful.
+ *
+ *	In either case, if the function fails, it must return FAIL and 
+ *	push error information onto the error stack with the error API 
+ *	routines, and return without modifying the values pointed to by 
+ *	the image_len_ptr, compressed_ptr, and compressed_image_len_ptr
+ *	parameters.
+ *
+ * PRE_SERIALIZE: Pointer to the pre-serialize callback.
+ *
+ *	The pre-serialize callback is invoked by the metadata cache before
+ *	it needs a current on-disk image of the metadata entry for purposes
+ *	either constructing a journal or flushing the entry to disk.
+ *
+ *      If the client needs to change the address or compressed or 
+ *	uncompressed length of the entry prior to flush, the pre-serialize 
+ *	callback is responsible for these actions, so that the actual 
+ *	serialize callback (described below) is only responsible for 
+ *	serializing the data structure, not moving it on disk or resizing it.
+ *
+ *	In addition, the client may use the pre-serialize callback to 
+ *	ensure that the entry is ready to be flushed -- in particular, 
+ *	if the entry contains references to other entries that are in 
+ *	temporary file space, the pre-serialize callback must move those
+ *	entries into real file space so that the serialzed entry will 
+ *	contain no invalid data.
+ *
+ *	One would think that the base address and length of
+ *	the length of the entry's image on disk would be well known. 
+ *	However, that need not be the case as free space section info
+ *	entries will change size (and possibly location) depending on the 
+ *	number of blocks of free space being manages, and fractal heap 
+ *	direct blocks can change compressed size (and  possibly location) 
+ *	on serialization if compression is enabled.  Similarly, it may
+ *	be necessary to move entries from temporary to real file space.
+ *
+ *	The pre-serialize callback must report any such changes to the 
+ *	cache, which must then update its internal structures as needed.
+ *
+ *	The typedef for the pre-serialize callback is as follows:
+ *
+ *	typedef herr_t (*H5C_pre_serialize_func_t)(const H5F_t *f,
+ *                                             hid_t dxpl_id,
+ *                                             void * thing,
+ *                                             haddr_t addr,
+ *                                             size_t len,
+ *					       size_t compressed_len,
+ *                                             haddr_t * new_addr_ptr,
+ *                                             size_t * new_len_ptr,
+ *					       size_t * new_compressed_len_ptr,
+ *                                             unsigned * flags_ptr);
+ *
+ *	The parameters of the pre-serialize callback are as follows:
+ *
+ *	f:	File pointer -- needed if other metadata cache entries
+ *		must be modified in the process of serializing the
+ *		target entry.
+ *
+ *	dxpl_id: dxpl_id passed with the file pointer to the cache, and
+ *	        passed on to the callback.  Necessary as some callbacks
+ *	        revise the size and location of the target entry, or
+ *	        possibly other entries on pre-serialize.
+ *
+ *	thing:  Pointer to void containing the address of the in core
+ *		representation of the target metadata cache entry. 
+ *		This is the same pointer returned by a protect of the
+ *		addr and len given above.
+ *
+ *	addr:   Base address in file of the entry to be serialized.
+ *
+ *		This parameter is supplied mainly for sanity checking.
+ *		Sanity checks should be performed when compiled in debug
+ *		mode, but the parameter may be unused when compiled in
+ *		production mode.
+ *
+ *	len:    Length in bytes of the in file image of the entry to be
+ *		serialized.  Also the size the image passed to the 
+ *		serialize callback (discussed below) unless either that 
+ *		value is altered by this function, or the entry will be
+ *		compressed.  In the latter case, the compressed size
+ *		of the entry will be reported in *new_compressed_len_ptr.
+ *
+ *		This parameter is supplied mainly for sanity checking.
+ *		Sanity checks should be performed when compiled in debug
+ *		mode, but the parameter may be unused when compiled in
+ *		production mode.
+ *
+ *	compressed_len: If the entry is to be compressed (i.e. run through 
+ *		filters) prior to flush, Length in bytes of the last know 
+ *		compressed size of the entry -- or the uncompressed size 
+ *		if no such value exists (i.e. the entry has been inserted, 
+ *		but never flushed).  This parameter should be set to zero
+ *		in all other cases.
+ *
+ *		This parameter is supplied mainly for sanity checking.
+ *		Sanity checks should be performed when compiled in debug
+ *		mode, but the parameter may be unused when compiled in
+ *		production mode.
+ *
+ *	new_addr_ptr:  Pointer to haddr_t.  If the entry is moved by
+ *		the serialize function, the new on disk base address must
+ *		be stored in *new_addr_ptr, and the appropriate flag set
+ *		in *flags_ptr.  
+ *
+ *		If the entry is not moved by the serialize function, 
+ *		*new_addr_ptr is undefined on pre-serialize callback 
+ *		return.
+ *
+ *	new_len_ptr:  Pointer to size_t.  If the entry is resized by the
+ *		serialize function, the new length of the on disk image
+ *		must be stored in *new_len_ptr, and the appropriate flag set
+ *              in *flags_ptr.
+ *
+ *		If the entry is not resized by the pre-serialize function, 
+ *		*new_len_ptr is undefined on pre-serialize callback 
+ *		return.
+ *
+ *	new_compressed_len_ptr: Pointer to size_t.  If the image will be
+ *		compressed (i.e. run through filters) prior to being 
+ *		written to disk, the compressed size (in bytes) of the
+ *		on disk image must be stored in *new_compressed_len_ptr,
+ *		and the appropriate flag set in *flags_ptr.  
+ *
+ *	flags_ptr:  Pointer to an unsigned integer used to return flags
+ *		indicating whether the preserialize function resized or moved
+ *		the entry, or computed its compressed size.  If the entry was 
+ *		neither resized or moved, nor will be compressed,
+ *		the serialize function must set *flags_ptr to zero. 
+ *		H5C__SERIALIZE_RESIZED_FLAG, H5C__SERIALIZE_MOVED_FLAG
+ *		and H5C__SERIALIZE_COMPRESSED_FLAG must be set to indicate 
+ *		a resize, a move, or compression respectively.
+ *
+ *	        If the H5C__SERIALIZE_RESIZED_FLAG is set, the new length
+ *	        must be stored in *new_len_ptr.
+ *
+ *	        If the H5C__SERIALIZE_MOVED_FLAG flag is set, the
+ *	        new image base address must be stored in *new_addr_ptr. 
+ *
+ *		If the H5C__SERIALIZE_COMPRESSED_FLAG is set, the 
+ *		compressed size of the new image must be stored in 
+ *		*new_compressed_len_ptr. 
+ *
+ *	Processing in the pre-serialize function should proceed as follows:
+ *
+ *	The pre-serialize function must examine the in core representation
+ *	indicated by the thing parameter, if the pre-serialize function does
+ *      not need to change the size or location of the on-disk image, or
+ *	compute its compress size, it must set *flags_ptr to zero. 
+ *
+ *	If the (uncompressed) size of the on-disk image must be changed, 
+ *	the pre-serialize function must load the length of the new image 
+ *	into *new_len_ptr, and set the H5C__SERIALIZE_RESIZED_FLAG in 
+ *	*flags_ptr. 
+ *
+ *	If the base address of the on disk image must be changed, the
+ *      pre-serialize function must set *new_addr_ptr to the new base address,
+ *      and set the H5C__SERIALIZE_MOVED_FLAG in *flags_ptr.
+ *
+ *	If the H5C__CLASS_COMPRESSED_FLAG is set in the assocated instance
+ *	of H5C_class_t, and filters (i.e. compression) are enabled, the 
+ *	pre-serialize function must compute the compressed size of the 
+ *	on disk image, and if it has changed, load this value into 
+ *	*new_compressed_len_ptr, and set H5C__SERIALIZE_COMPRESSED_FLAG in 
+ *	*flags_ptr.
+ *
+ *	Note that to do this, the preserialize function will typically have 
+ *	to serialize the entry, and run it through the filters to obtain 
+ *	the compressed size.  For efficiency, the compressed image may
+ *	be stored to be copied into the supplied buffer by the 
+ *	serialize callback.  Needless to say this is awkward.  We may
+ *	want to re-work the API for cache clients to simplify this.
+ *
+ *	In addition, the pre-serialize callback may perform any other 
+ *	processing required before the entry is written to disk
+ *
+ *	If it is successful, the function must return SUCCEED. 
+ *
+ *	If it fails for any reason, the function must return FAIL and
+ *	push error information on the error stack with the error API
+ *	routines.
+ *
+ *
+ * SERIALIZE: Pointer to the serialize callback.
+ *
+ *	The serialize callback is invoked by the metadata cache whenever
+ *	it needs a current on disk image of the metadata entry for purposes
+ *	either constructing a journal entry or flushing the entry to disk.
+ *
+ *	At this point, the base address and length of the entry's image on
+ *      disk must be well known and not change during the serialization
+ *      process. 
+ *
+ *	While any size and/or location changes must have been handled 
+ *	by a pre-serialize call, the client may elect to handle any other 
+ *	changes to the entry required to place it in correct form for 
+ *	writing to disk in this call.
+ *
+ *	The typedef for the serialize callback is as follows:
+ *
+ *	typedef herr_t (*H5C_serialize_func_t)(const H5F_t *f,
+ *                                             void * image_ptr,
+ *                                             size_t len,
+ *                                             void * thing);
+ *
+ *	The parameters of the serialize callback are as follows:
+ *
+ *	f:	File pointer -- needed if other metadata cache entries
+ *		must be modified in the process of serializing the
+ *		target entry.
+ *
+ *	image_ptr: Pointer to a buffer of length len bytes into which a
+ *		serialized image of the target metadata cache entry is
+ *		to be written.
+ *
+ * 		Note that this buffer will not in general be initialized
+ * 		to any particular value.  Thus the serialize function may
+ * 		not assume any initial value and must set each byte in
+ * 		the buffer.
+ *
+ *	len:    Length in bytes of the in file image of the entry to be
+ *		serialized.  Also the size of *image_ptr (below).  If 
+ *		compression is not enabled, this value is simply the 
+ *		uncompressed size of the entry's image on disk.  If 
+ *		compression is enabled, this value is the size of the 
+ *		compressed image.
+ *
+ *		This parameter is supplied mainly for sanity checking.
+ *		Sanity checks should be performed when compiled in debug
+ *		mode, but the parameter may be unused when compiled in
+ *		production mode.
+ *
+ *	thing:  Pointer to void containing the address of the in core
+ *		representation of the target metadata cache entry. 
+ *		This is the same pointer returned by a protect of the
+ *		addr and len given above.
+ *
+ *	Processing in the serialize function should proceed as follows:
+ *
+ *	If there are any remaining changes to the entry required before 
+ *	write to disk, they must be dealt with first.
+ *
+ *	The serialize function must then examine the in core 
+ *	representation indicated by the thing parameter, and write a 
+ *	serialized (and possibly compressed) image of its contents into 
+ *	the provided buffer. 
+ *
+ *	If it is successful, the function must return SUCCEED. 
+ *
+ *	If it fails for any reason, the function must return FAIL and
+ *	push error information on the error stack with the error API
+ *	routines.
+ *
+ *
+ * NOTIFY: Pointer to the notify callback.
+ *
+ *      The notify callback is invoked by the metadata cache when a cache
+ *      action on an entry has taken/will take place and the client indicates
+ *      it wishes to be notified about the action.
+ *
+ *	The typedef for the notify callback is as follows:
+ *
+ *	typedef herr_t (*H5C_notify_func_t)(H5C_notify_action_t action,
+ *                                          void *thing);
+ *
+ * 	The parameters of the notify callback are as follows:
+ *
+ *	action: An enum indicating the metadata cache action that has taken/
+ *              will take place.
+ *
+ *	thing:  Pointer to void containing the address of the in core
+ *		representation of the target metadata cache entry.  This
+ *		is the same pointer that would be returned by a protect
+ *		of the addr and len of the entry. 
+ *
+ *	Processing in the notify function should proceed as follows:
+ *
+ *	The notify function may perform any action it would like, including
+ *      metadata cache calls.
+ *
+ *	If the function is successful, it must return SUCCEED. 
+ *
+ *	If it fails for any reason, the function must return FAIL and
+ *	push error information on the error stack with the error API
+ *	routines. 
+ *
+ *
+ * FREE_ICR: Pointer to the free ICR callback.
+ *
+ *	The free ICR callback is invoked by the metadata cache when it
+ *	wishes to evict an entry, and needs the client to free the memory
+ *	allocated for the in core representation. 
+ *
+ *	The typedef for the free ICR callback is as follows:
+ *
+ *	typedef herr_t (*H5C_free_icr_func_t)(void * thing));
+ *
+ * 	The parameters of the free ICR callback are as follows:
+ *
+ *	thing:  Pointer to void containing the address of the in core
+ *		representation of the target metadata cache entry.  This
+ *		is the same pointer that would be returned by a protect
+ *		of the addr and len of the entry. 
+ *
+ *	Processing in the free ICR function should proceed as follows:
+ *
+ *	The free ICR function must free all memory allocated to the
+ *	in core representation. 
+ *
+ *	If the function is successful, it must return SUCCEED. 
+ *
+ *	If it fails for any reason, the function must return FAIL and
+ *	push error information on the error stack with the error API
+ *	routines. 
+ *
+ *	At least when compiled with debug, it would be useful if the
+ *	free ICR call would fail if the in core representation has been
+ *	modified since the last serialize of clear callback.
+ *
+ * CLEAR: Pointer to the clear callback.
+ *
+ *	In principle, there should be no need for the clear callback,
+ *	as the dirty flag should be maintained by the metadata cache.
+ *.  
+ *	However, some clients maintain dirty bits on internal data, 
+ *	and we need some way of keeping these dirty bits in sync with 
+ *	those maintained by the metadata cache.  This callback exists
+ *	to serve this purpose.  If defined, it is called whenever the 
+ *	cache marks dirty entry clean, or when the cache is about to 
+ *	discard a dirty entry without writing it to disk (This 
+ *	happens as the result of an unprotect call with the 
+ *	H5AC__DELETED_FLAG set, and the H5C__TAKE_OWNERSHIP_FLAG not
+ *	set.)
+ *
+ *	Arguably, this functionality should be in the NOTIFY callback.
+ *	However, this callback is specific to only a few clients, and 
+ *	it will be called relatively frequently.  Hence it is made its
+ *	own callback to minimize overhead.
+ *
+ *	The typedef for the clear callback is as follows:
+ *
+ *	typedef herr_t (*H5C_clear_func_t)(const H5F_t *f,
+ *                                         void * thing, 
+ *                                         hbool_t about_to_destroy);
+ *
+ *	The parameters of the clear callback are as follows:
+ *
+ *	f:	File pointer.
+ *
+ *	thing:  Pointer to void containing the address of the in core
+ *		representation of the target metadata cache entry.  This
+ *		is the same pointer that would be returned by a protect()
+ *		call of the associated addr and len.
+ *
+ *	about_to_destroy: Boolean flag used to indicate whether the 
+ *		metadata cache is about to destroy the target metadata
+ *		cache entry.  The callback may use this flag to omit
+ *		operations that are irrelevant it the entry is about 
+ *		to be destroyed.
+ *
+ *	Processing in the clear function should proceed as follows:
+ *
+ *	Reset all internal dirty bits in the target metadata cache entry.
+ *
+ *	If the about_to_destroy flag is TRUE, the clear function may 
+ *	ommit any dirty bit that will not trigger a sanity check failure 
+ *	or otherwise cause problems in the subsequent free icr call.
+ *	In particular, the call must ensure that the free icr call will
+ *	not fail due to changes prior to this call, and after the 
+ *	last serialize or clear call.
+ *
+ *	If the function is successful, it must return SUCCEED. 
+ *
+ *	If it fails for any reason, the function must return FAIL and
+ *	push error information on the error stack with the error API
+ *	routines. 
+ *
+ * GET_FSF_SIZE: Pointer to the get file space free size callback.
+ *
+ *	In principle, there is no need for the get file space free size
+ *	callback.  However, as an optimization, it is sometimes convenient
+ *	to allocate and free file space for a number of cache entries 
+ *	simultaneously in a single contiguous block of file space.
+ *
+ *	File space allocation is done by the client, so the metadata cache
+ *	need not be involved.  However, since the metadata cache typically
+ *      handles file space release when an entry is destroyed, some 
+ *	adjustment on the part of the metadata cache is required for this
+ *	operation.
+ *
+ *      The get file space free size callback exists to support this 
+ *	operation.
+ *
+ *	If a group of cache entries that were allocated as a group are to 
+ *	be discarded and their file space released, the type of the first
+ *	(i.e. lowest address) entry in the group must implement the 
+ *	get free file space size callback.  
+ *
+ *	To free the file space of all entries in the group in a single 
+ *	operation, first expunge all entries other than the first without 
+ *	the free file space flag.  
+ *
+ *	Then, to complete the operation, unprotect or expunge the first
+ *	entry in the block with the free file space flag set.  Since 
+ *	the get free file space callback is implemented, the metadata 
+ *	cache will use this callback to get the size of the block to be
+ *	freed, instead of using the size of the entry as is done otherwise.
+ *
+ *	At present this callback is used only by the H5FA and H5EA dblock
+ *	and dblock page client classes.
+ *
+ *      The typedef for the clear callback is as follows:
+ *
+ *      typedef herr_t (*H5C_get_fsf_size_t)(const void * thing,
+ *                                                size_t *fsf_size_ptr);
+ *
+ *      The parameters of the clear callback are as follows:
+ *
+ *      thing:  Pointer to void containing the address of the in core
+ *              representation of the target metadata cache entry.  This
+ *              is the same pointer that would be returned by a protect()
+ *              call of the associated addr and len.
+ *
+ *	fs_size_ptr: Pointer to size_t in which the callback will return
+ *              the size of the piece of file space to be freed.  Note 
+ *		that the space to be freed is presumed to have the same 
+ *		base address as the cache entry.
+ *
+ *      The function simply returns the size of the block of file space
+ *	to be freed in *fsf_size_ptr.  
+ *
+ *	If the function is successful, it must return SUCCEED.
+ *
+ *      If it fails for any reason, the function must return FAIL and
+ *      push error information on the error stack with the error API
+ *      routines.
+ *
+ ***************************************************************************/
 
 /* Actions that can be reported to 'notify' client callback */
 typedef enum H5C_notify_action_t {
-    H5C_NOTIFY_ACTION_AFTER_INSERT,     /* Entry has been added to the cache */
-                                        /* (could be loaded from file with
-                                         *      'protect' call, or inserted
-                                         *      with 'set' call)
+    H5C_NOTIFY_ACTION_AFTER_INSERT,     /* Entry has been added to the cache 
+                                         * via the insert call
+                                         */
+    H5C_NOTIFY_ACTION_AFTER_LOAD,	/* Entry has been loaded into the 
+                                         * from file via the protect call
+                                         */
+    H5C_NOTIFY_ACTION_AFTER_FLUSH,	/* Entry has just been flushed to
+ 					 * file.
+                                         */
+    H5C_NOTIFY_ACTION_BEFORE_EVICT      /* Entry is about to be evicted 
+                                         * from cache.
                                          */
-    H5C_NOTIFY_ACTION_BEFORE_EVICT      /* Entry is about to be evicted from cache */
 } H5C_notify_action_t;
 
 /* Cache client callback function pointers */
-typedef void *(*H5C_load_func_t)(H5F_t *f, hid_t dxpl_id, haddr_t addr,
-    void *udata);
-typedef herr_t (*H5C_flush_func_t)(H5F_t *f, hid_t dxpl_id, hbool_t dest,
-    haddr_t addr, void *thing, unsigned *flags_ptr);
-typedef herr_t (*H5C_dest_func_t)(H5F_t *f, void *thing);
-typedef herr_t (*H5C_clear_func_t)(H5F_t *f, void *thing, hbool_t dest);
+typedef herr_t (*H5C_get_load_size_func_t)(const void *udata_ptr,
+    size_t *image_len_ptr);
+typedef void *(*H5C_deserialize_func_t)(const void *image_ptr,
+    size_t len, void *udata_ptr, hbool_t *dirty_ptr);
+typedef herr_t (*H5C_image_len_func_t)(const void *thing,
+    size_t *image_len_ptr, hbool_t *compressed_ptr, size_t *compressed_image_len_ptr);
+typedef herr_t (*H5C_pre_serialize_func_t)(const H5F_t *f, hid_t dxpl_id,
+    void *thing, haddr_t addr, size_t len, size_t compressed_len,
+    haddr_t *new_addr_ptr, size_t *new_len_ptr, size_t *new_compressed_len_ptr,
+    unsigned *flags_ptr);
+typedef herr_t (*H5C_serialize_func_t)(const H5F_t *f, void *image_ptr,
+    size_t len, void *thing);
 typedef herr_t (*H5C_notify_func_t)(H5C_notify_action_t action, void *thing);
-typedef herr_t (*H5C_size_func_t)(const H5F_t *f, const void *thing,
-    size_t *size_ptr);
+typedef herr_t (*H5C_free_icr_func_t)(void *thing);
+typedef herr_t (*H5C_clear_func_t)(const H5F_t *f, void * thing, 
+    hbool_t about_to_destroy);
+typedef herr_t (*H5C_get_fsf_size_t)(const void * thing, size_t *fsf_size_ptr);
 
 /* Metadata cache client class definition */
 typedef struct H5C_class_t {
-    int			id;
-    H5C_load_func_t	load;
-    H5C_flush_func_t	flush;
-    H5C_dest_func_t	dest;
-    H5C_clear_func_t	clear;
-    H5C_notify_func_t	notify;
-    H5C_size_func_t	size;
+    int				id;
+    const char *		name;
+    H5FD_mem_t			mem_type;
+    unsigned			flags;
+    H5C_get_load_size_func_t 	get_load_size;
+    H5C_deserialize_func_t 	deserialize;
+    H5C_image_len_func_t	image_len;
+    H5C_pre_serialize_func_t	pre_serialize;
+    H5C_serialize_func_t	serialize;
+    H5C_notify_func_t		notify;
+    H5C_free_icr_func_t	        free_icr;
+    H5C_clear_func_t		clear;
+    H5C_get_fsf_size_t		fsf_size;
 } H5C_class_t;
 
 /* Type defintions of callback functions used by the cache as a whole */
@@ -312,7 +1130,7 @@ typedef herr_t (*H5C_log_flush_func_t)(H5C_t *cache_ptr, haddr_t addr,
  *              just before the entry is freed.
  *
  *              This is necessary, as the LRU list can be changed out
- *              from under H5C_make_space_in_cache() by the flush
+ *              from under H5C_make_space_in_cache() by the serialize
  *              callback which may change the size of an existing entry,
  *              and/or load a new entry while serializing the target entry.
  *
@@ -325,18 +1143,66 @@ typedef herr_t (*H5C_log_flush_func_t)(H5C_t *cache_ptr, haddr_t addr,
  *              detect this case, and re-start its scan from the bottom
  *              of the LRU when this situation occurs.
  *
- *              This field is only compiled in debug mode.
+ * cache_ptr:	Pointer to the cache that this entry is contained within.
  *
  * addr:	Base address of the cache entry on disk.
  *
- * size:	Length of the cache entry on disk.  Note that unlike normal
- *		caches, the entries in this cache are of variable length.
- *		The entries should never overlap, and when we do writebacks,
- *		we will want to writeback adjacent entries where possible.
+ * size:	Length of the cache entry on disk in bytes(exception: if 
+ *		the entry is compressed on disk, this field contains the 
+ *		uncompressed size of the entry -- see discussion of 
+ *		compressed entries below).  Note that unlike normal 
+ *		caches, the entries in this cache are of arbitrary size.
+ *
+ *		With the exception of compressed entries, the file space
+ *		allocations for cache entries implied by the addr and size
+ *		fields must be disjoint.  For compressed entries,
+ *		the size field contains the uncompressed size -- thus in
+ *		in this case, substitution of compressed size for size 
+ *		must result in disjoint file space allocations.  However, 
+ *		as discussed below, the compressed size may not be know.
+ *
+ *		Any entry whose associated instance of H5C_class_t has the
+ *		H5C__CLASS_COMPRESSED_FLAG set may be compressed.  When
+ *		an entry is compressed (that is, when filters are enabled
+ *		on it), the compressed flag (see below) must be set, and 
+ *		the compressed size (if known), must be stored in 
+ *		the compressed_size field.
+ *
+ *		Since the compressed size will be unknown unless the 
+ *		entry is clean, or has an up to date image (see the 
+ *		image_ptr and image_up_to_date fields below), we use the 
+ *		uncompressed size for all purposes other than disk I/O.  
+ *		
+ * compressed:	Boolean flag that is set iff the instance of H5C_class_t
+ *		associated with the entry has the H5C__CLASS_COMPRESSED_FLAG
+ *		set, and filters are enabled on the entry.
+ *
+ * compressed_size: If compressed is TRUE, this field contains the actual
+ *		compressed size of the entry in bytes, which is also its 
+ *		true size on disk -- or the uncompressed size if the 
+ *		compressed size is unknown (i.e. the entry has been 
+ *		inserted in the cache, but it has not been compressed yet).
+ *              Note that this value will usually be incorrect if the 
+ *		entry is dirty.
+ *
+ *		Since this value is frequently out of date and expensive to 
+ *		compute, it is used only for disk I/O.  The uncompressed 
+ *		size of the entry (stored in the size field above) is used 
+ *		for all other purposes (i.e. computing the sum of the sizes 
+ *		of all entries in the cache, etc.).
+ *
+ *		If compressed is FALSE, this field should contain 0.
+ *
+ * image_ptr:	Pointer to void.  When not NULL, this field points to a
+ * 		dynamically allocated block of size bytes in which the
+ * 		on disk image of the metadata cache entry is stored.
+ *
+ * 		If the entry is dirty, the pre-serialize and serialize 
+ *		callbacks must be used to update this image before it is 
+ *		written to disk
  *
- *		NB: At present, entries need not be contiguous on disk.  Until
- *		    we fix this, we can't do much with writing back adjacent
- *		    entries.
+ * image_up_to_date:  Boolean flag that is set to TRUE when *image_ptr
+ * 		is up to date, and set to false when the entry is dirtied.
  *
  * type:	Pointer to the instance of H5C_class_t containing pointers
  *		to the methods for cache entries of the current type.  This
@@ -366,6 +1232,9 @@ typedef herr_t (*H5C_log_flush_func_t)(H5C_t *cache_ptr, haddr_t addr,
  *		      modules using the cache.  These still clear the
  *		      is_dirty field as before.  -- JRM 7/5/05
  *
+ *		Update: Management of the is_dirty field is now entirely
+ *		      in the cache.		 -- JRM 7/5/07
+ *
  * dirtied:	Boolean flag used to indicate that the entry has been
  * 		dirtied while protected.
  *
@@ -422,9 +1291,10 @@ typedef herr_t (*H5C_log_flush_func_t)(H5C_t *cache_ptr, haddr_t addr,
  * 		   policy code (LRU at present).
  *
  * 		2) A pinned entry can be accessed or modified at any time.
- * 		   Therefore, the cache must check with the entry owner
- * 		   before flushing it.  If permission is denied, the
- * 		   cache does not flush the entry.
+ * 		   This places an extra burden on the pre-serialize and 
+ *		   serialize callbacks, which must ensure that a pinned 
+ *		   entry is consistant and ready to write to disk before 
+ *		   generating an image.
  *
  * 		3) A pinned entry can be marked as dirty (and possibly
  *		   change size) while it is unprotected.
@@ -466,6 +1336,11 @@ typedef herr_t (*H5C_log_flush_func_t)(H5C_t *cache_ptr, haddr_t addr,
  *              will need to be expanded and tested appropriately if that
  *              functionality is desired.
  *
+ *		Update: There are now two possible last entries
+ *                   	(superblock and file driver info message).  This
+ *                   	number will probably increase as we add superblock
+ *                   	messages.   JRM -- 11/18/14
+ *
  * clear_on_unprotect:  Boolean flag used only in PHDF5.  When H5C is used
  *		to implement the metadata cache In the parallel case, only
  *		the cache with mpi rank 0 is allowed to actually write to
@@ -493,11 +1368,6 @@ typedef herr_t (*H5C_log_flush_func_t)(H5C_t *cache_ptr, haddr_t addr,
  * destroy_in_progress:  Boolean flag that is set to true iff the entry
  * 		is in the process of being flushed and destroyed.
  *
- * free_file_space_on_destroy:  Boolean flag that is set to true iff the entry
- * 		is in the process of being flushed and destroyed and the file
- *              space used by the object should be freed by the cache client's
- *              'dest' callback routine.
- *
  *
  * Fields supporting the 'flush dependency' feature:
  *
@@ -581,63 +1451,43 @@ typedef herr_t (*H5C_log_flush_func_t)(H5C_t *cache_ptr, haddr_t addr,
  * The use of the replacement policy fields under the Modified LRU policy
  * is discussed below:
  *
- * next:	Next pointer in either the LRU or the protected list,
- *		depending on the current value of protected.  If there
- *		is no next entry on the list, this field should be set
- *		to NULL.
+ * next:	Next pointer in either the LRU, the protected list, or 
+ *		the pinned list depending on the current values of 
+ *		is_protected and is_pinned.  If there is no next entry 
+ *		on the list, this field should be set to NULL.
  *
- * prev:	Prev pointer in either the LRU or the protected list,
- *		depending on the current value of protected.  If there
- *		is no previous entry on the list, this field should be
- *		set to NULL.
+ * prev:	Prev pointer in either the LRU, the protected list,
+ *		or the pinned list depending on the current values of 
+ *		is_protected and is_pinned.  If there is no previous 
+ *		entry on the list, this field should be set to NULL.
  *
  * aux_next:	Next pointer on either the clean or dirty LRU lists.
- *		This entry should be NULL when protected is true.  When
- *		protected is false, and dirty is true, it should point
- *		to the next item on the dirty LRU list.  When protected
- *		is false, and dirty is false, it should point to the
- *		next item on the clean LRU list.  In either case, when
- *		there is no next item, it should be NULL.
+ *		This entry should be NULL when either is_protected or 
+ *		is_pinned is true.  
+ *
+ *		When is_protected and is_pinned are false, and is_dirty is 
+ *		true, it should point to the next item on the dirty LRU 
+ *		list.  
+ *
+ *		When is_protected and is_pinned are false, and is_dirty is 
+ *		false, it should point to the next item on the clean LRU 
+ *		list.  In either case, when there is no next item, it 
+ *		should be NULL.
  *
  * aux_prev:	Previous pointer on either the clean or dirty LRU lists.
- *		This entry should be NULL when protected is true.  When
- *		protected is false, and dirty is true, it should point
- *		to the previous item on the dirty LRU list.  When protected
- *		is false, and dirty is false, it should point to the
- *		previous item on the clean LRU list.  In either case, when
- *		there is no previous item, it should be NULL.
- *
- *
- * Fields supporting metadata journaling:
- *
- * last_trans:	unit64_t containing the ID of the last transaction in
- * 		which this entry was dirtied.  If journaling is disabled,
- * 		or if the entry has never been dirtied in a transaction,
- * 		this field should be set to zero.  Once we notice that
- * 		the specified transaction has made it to disk, we will
- * 		reset this field to zero as well.
- *
- * 		We must maintain this field, as to avoid messages from
- * 		the future, we must not flush a dirty entry to disk
- * 		until the last transaction in which it was dirtied
- * 		has made it to disk in the journal file.
- *
- * trans_next:  Next pointer in the entries modified in the current
- * 		transaction list.  This field should always be null
- * 		unless journaling is enabled, the entry is dirty,
- * 		and last_trans field contains the current transaction
- * 		number.  Even if all these conditions are fulfilled,
- * 		the field will still be NULL if this is the last
- * 		entry on the list.
- *
- * trans_prev:  Previous pointer in the entries modified in the current
- * 		transaction list.  This field should always be null
- * 		unless journaling is enabled, the entry is dirty,
- * 		and last_trans field contains the current transaction
- * 		number.  Even if all these conditions are fulfilled,
- * 		the field will still be NULL if this is the first
- * 		entry on the list.
+ *		This entry should be NULL when either is_protected or 
+ *		is_pinned is true.  
+ *
+ *		When is_protected and is_pinned are false, and is_dirty is 
+ *		true, it should point to the previous item on the dirty 
+ *		LRU list.  
+ *	
+ *		When is_protected and is_pinned are false, and is_dirty 
+ *		is false, it should point to the previous item on the 
+ *		clean LRU list.  
  *
+ *		In either case, when there is no previous item, it should 
+ *		be NULL.
  *
  * Cache entry stats collection fields:
  *
@@ -659,12 +1509,14 @@ typedef herr_t (*H5C_log_flush_func_t)(H5C_t *cache_ptr, haddr_t addr,
  *
  ****************************************************************************/
 typedef struct H5C_cache_entry_t {
-#ifndef NDEBUG
     uint32_t			magic;
-#endif /* NDEBUG */
     H5C_t                     * cache_ptr;
     haddr_t			addr;
     size_t			size;
+    hbool_t			compressed;
+    size_t			compressed_size;
+    void  		      *	image_ptr;
+    hbool_t			image_up_to_date;
     const H5C_class_t	      *	type;
     haddr_t		        tag;
     hbool_t			is_dirty;
@@ -683,7 +1535,6 @@ typedef struct H5C_cache_entry_t {
 #endif /* H5_HAVE_PARALLEL */
     hbool_t			flush_in_progress;
     hbool_t			destroy_in_progress;
-    hbool_t		        free_file_space_on_destroy;
 
     /* fields supporting the 'flush dependency' feature: */
     struct H5C_cache_entry_t  *	flush_dep_parent;
@@ -1012,12 +1863,11 @@ H5_DLL void H5C_def_auto_resize_rpt_fcn(H5C_t *cache_ptr, int32_t version,
     double hit_rate, enum H5C_resize_status status,
     size_t old_max_cache_size, size_t new_max_cache_size,
     size_t old_min_clean_size, size_t new_min_clean_size);
-H5_DLL herr_t H5C_dest(H5F_t *f, hid_t primary_dxpl_id, hid_t secondary_dxpl_id);
-H5_DLL herr_t H5C_expunge_entry(H5F_t *f, hid_t primary_dxpl_id, hid_t secondary_dxpl_id,
+H5_DLL herr_t H5C_dest(H5F_t *f, hid_t dxpl_id);
+H5_DLL herr_t H5C_expunge_entry(H5F_t *f, hid_t dxpl_id,
     const H5C_class_t *type, haddr_t addr, unsigned flags);
-H5_DLL herr_t H5C_flush_cache(H5F_t *f, hid_t primary_dxpl_id, hid_t secondary_dxpl_id,
-    unsigned flags);
-H5_DLL herr_t H5C_flush_to_min_clean(H5F_t *f, hid_t primary_dxpl_id, hid_t secondary_dxpl_id);
+H5_DLL herr_t H5C_flush_cache(H5F_t *f, hid_t dxpl_id, unsigned flags);
+H5_DLL herr_t H5C_flush_to_min_clean(H5F_t *f, hid_t dxpl_id);
 H5_DLL herr_t H5C_get_cache_auto_resize_config(const H5C_t *cache_ptr,
     H5C_auto_size_ctl_t *config_ptr);
 H5_DLL herr_t H5C_get_cache_size(H5C_t *cache_ptr, size_t *max_size_ptr,
@@ -1031,17 +1881,17 @@ H5_DLL herr_t H5C_get_entry_status(const H5F_t *f, haddr_t addr,
 H5_DLL herr_t H5C_get_evictions_enabled(const H5C_t *cache_ptr, hbool_t *evictions_enabled_ptr);
 H5_DLL FILE *H5C_get_trace_file_ptr(const H5C_t *cache_ptr);
 H5_DLL FILE *H5C_get_trace_file_ptr_from_entry(const H5C_cache_entry_t *entry_ptr);
-H5_DLL herr_t H5C_insert_entry(H5F_t *f, hid_t primary_dxpl_id, hid_t secondary_dxpl_id,
-    const H5C_class_t *type, haddr_t addr, void *thing, unsigned int flags);
-H5_DLL herr_t H5C_mark_entries_as_clean(H5F_t *f, hid_t primary_dxpl_id,
-    hid_t secondary_dxpl_id, int32_t ce_array_len, haddr_t *ce_array_ptr);
+H5_DLL herr_t H5C_insert_entry(H5F_t *f, hid_t dxpl_id, const H5C_class_t *type,
+    haddr_t addr, void *thing, unsigned int flags);
+H5_DLL herr_t H5C_mark_entries_as_clean(H5F_t *f, hid_t dxpl_id, int32_t ce_array_len,
+    haddr_t *ce_array_ptr);
 H5_DLL herr_t H5C_mark_entry_dirty(void *thing);
 H5_DLL herr_t H5C_move_entry(H5C_t *cache_ptr, const H5C_class_t *type,
     haddr_t old_addr, haddr_t new_addr);
 H5_DLL herr_t H5C_pin_protected_entry(void *thing);
 H5_DLL herr_t H5C_create_flush_dependency(void *parent_thing, void *child_thing);
-H5_DLL void * H5C_protect(H5F_t *f, hid_t primary_dxpl_id, hid_t secondary_dxpl_id,
-    const H5C_class_t *type, haddr_t addr, void *udata, unsigned flags);
+H5_DLL void * H5C_protect(H5F_t *f, hid_t dxpl_id, const H5C_class_t *type,
+    haddr_t addr, void *udata, unsigned flags);
 H5_DLL herr_t H5C_reset_cache_hit_rate_stats(H5C_t *cache_ptr);
 H5_DLL herr_t H5C_resize_entry(void *thing, size_t new_size);
 H5_DLL herr_t H5C_set_cache_auto_resize_config(H5C_t *cache_ptr,
@@ -1055,17 +1905,17 @@ H5_DLL void H5C_stats__reset(H5C_t *cache_ptr);
 H5_DLL herr_t H5C_dump_cache(H5C_t *cache_ptr, const char *cache_name);
 H5_DLL herr_t H5C_unpin_entry(void *thing);
 H5_DLL herr_t H5C_destroy_flush_dependency(void *parent_thing, void *child_thing);
-H5_DLL herr_t H5C_unprotect(H5F_t *f, hid_t primary_dxpl_id, hid_t secondary_dxpl_id,
-    const H5C_class_t *type, haddr_t addr, void *thing, unsigned int flags);
+H5_DLL herr_t H5C_unprotect(H5F_t *f, hid_t dxpl_id, const H5C_class_t *type,
+    haddr_t addr, void *thing, unsigned int flags);
 H5_DLL herr_t H5C_validate_resize_config(H5C_auto_size_ctl_t *config_ptr,
     unsigned int tests);
 H5_DLL herr_t H5C_ignore_tags(H5C_t *cache_ptr);
 H5_DLL void H5C_retag_copied_metadata(H5C_t *cache_ptr, haddr_t metadata_tag);
 
 #ifdef H5_HAVE_PARALLEL
-H5_DLL herr_t H5C_apply_candidate_list(H5F_t *f, hid_t primary_dxpl_id,
-    hid_t secondary_dxpl_id, H5C_t *cache_ptr, int num_candidates,
-    haddr_t *candidates_list_ptr, int mpi_rank, int mpi_size);
+H5_DLL herr_t H5C_apply_candidate_list(H5F_t *f, hid_t dxpl_id,
+    H5C_t *cache_ptr, int num_candidates, haddr_t *candidates_list_ptr,
+    int mpi_rank, int mpi_size);
 H5_DLL herr_t H5C_construct_candidate_list__clean_cache(H5C_t *cache_ptr);
 H5_DLL herr_t H5C_construct_candidate_list__min_clean(H5C_t *cache_ptr);
 #endif /* H5_HAVE_PARALLEL */