summaryrefslogtreecommitdiffstats
path: root/src/H5Cprivate.h
diff options
context:
space:
mode:
authorQuincey Koziol <koziol@hdfgroup.org>2015-06-18 00:58:49 (GMT)
committerQuincey Koziol <koziol@hdfgroup.org>2015-06-18 00:58:49 (GMT)
commitf30ab55f41296667eab0b273132ffc20c4323717 (patch)
tree2fd6a85b7c15e3505e308e21b41e67297cc58508 /src/H5Cprivate.h
parent6e9e9e0dd200979642de8d2a2bce2f66f9728237 (diff)
downloadhdf5-f30ab55f41296667eab0b273132ffc20c4323717.zip
hdf5-f30ab55f41296667eab0b273132ffc20c4323717.tar.gz
hdf5-f30ab55f41296667eab0b273132ffc20c4323717.tar.bz2
[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)
Diffstat (limited to 'src/H5Cprivate.h')
-rw-r--r--src/H5Cprivate.h1120
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 */