diff options
Diffstat (limited to 'src/H5ACpublic.h')
-rw-r--r-- | src/H5ACpublic.h | 251 |
1 files changed, 155 insertions, 96 deletions
diff --git a/src/H5ACpublic.h b/src/H5ACpublic.h index dd16764..654a877 100644 --- a/src/H5ACpublic.h +++ b/src/H5ACpublic.h @@ -5,12 +5,10 @@ * * * This file is part of HDF5. The full HDF5 copyright notice, including * * terms governing use, modification, and redistribution, is contained in * - * the files COPYING and Copyright.html. COPYING can be found at the root * - * of the source code distribution tree; Copyright.html can be found at the * - * root level of an installed copy of the electronic HDF5 document set and * - * is linked from the top-level documents page. It can also be found at * - * http://hdfgroup.org/HDF5/doc/Copyright.html. If you do not have * - * access to either file, you may request a copy from help@hdfgroup.org. * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://support.hdfgroup.org/ftp/HDF5/releases. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /*------------------------------------------------------------------------- @@ -70,65 +68,65 @@ extern "C" { * version number, or an error will be flagged. * * rpt_fcn_enabled: Boolean field used to enable and disable the default - * reporting function. This function is invoked every time the - * automatic cache resize code is run, and reports on its activities. + * reporting function. This function is invoked every time the + * automatic cache resize code is run, and reports on its activities. * - * This is a debugging function, and should normally be turned off. + * This is a debugging function, and should normally be turned off. * * open_trace_file: Boolean field indicating whether the trace_file_name - * field should be used to open a trace file for the cache. + * field should be used to open a trace file for the cache. * * *** DEPRECATED *** Use H5Fstart/stop logging functions instead * - * The trace file is a debuging feature that allow the capture of - * top level metadata cache requests for purposes of debugging and/or - * optimization. This field should normally be set to FALSE, as - * trace file collection imposes considerable overhead. + * The trace file is a debuging feature that allow the capture of + * top level metadata cache requests for purposes of debugging and/or + * optimization. This field should normally be set to FALSE, as + * trace file collection imposes considerable overhead. * - * This field should only be set to TRUE when the trace_file_name - * contains the full path of the desired trace file, and either - * there is no open trace file on the cache, or the close_trace_file - * field is also TRUE. + * This field should only be set to TRUE when the trace_file_name + * contains the full path of the desired trace file, and either + * there is no open trace file on the cache, or the close_trace_file + * field is also TRUE. * * close_trace_file: Boolean field indicating whether the current trace - * file (if any) should be closed. + * file (if any) should be closed. * * *** DEPRECATED *** Use H5Fstart/stop logging functions instead * - * See the above comments on the open_trace_file field. This field - * should be set to FALSE unless there is an open trace file on the - * cache that you wish to close. + * See the above comments on the open_trace_file field. This field + * should be set to FALSE unless there is an open trace file on the + * cache that you wish to close. * * trace_file_name: Full path of the trace file to be opened if the - * open_trace_file field is TRUE. + * open_trace_file field is TRUE. * * *** DEPRECATED *** Use H5Fstart/stop logging functions instead * - * In the parallel case, an ascii representation of the mpi rank of - * the process will be appended to the file name to yield a unique - * trace file name for each process. + * In the parallel case, an ascii representation of the mpi rank of + * the process will be appended to the file name to yield a unique + * trace file name for each process. * - * The length of the path must not exceed H5AC__MAX_TRACE_FILE_NAME_LEN - * characters. + * The length of the path must not exceed H5AC__MAX_TRACE_FILE_NAME_LEN + * characters. * * evictions_enabled: Boolean field used to either report the current - * evictions enabled status of the cache, or to set the cache's - * evictions enabled status. - * - * In general, the metadata cache should always be allowed to - * evict entries. However, in some cases it is advantageous to - * disable evictions briefly, and thereby postpone metadata - * writes. However, this must be done with care, as the cache - * can grow quickly. If you do this, re-enable evictions as - * soon as possible and monitor cache size. - * - * At present, evictions can only be disabled if automatic - * cache resizing is also disabled (that is, ( incr_mode == - * H5C_incr__off ) && ( decr_mode == H5C_decr__off )). There - * is no logical reason why this should be so, but it simplifies - * implementation and testing, and I can't think of any reason - * why it would be desireable. If you can think of one, I'll - * revisit the issue. + * evictions enabled status of the cache, or to set the cache's + * evictions enabled status. + * + * In general, the metadata cache should always be allowed to + * evict entries. However, in some cases it is advantageous to + * disable evictions briefly, and thereby postpone metadata + * writes. However, this must be done with care, as the cache + * can grow quickly. If you do this, re-enable evictions as + * soon as possible and monitor cache size. + * + * At present, evictions can only be disabled if automatic + * cache resizing is also disabled (that is, ( incr_mode == + * H5C_incr__off ) && ( decr_mode == H5C_decr__off )). There + * is no logical reason why this should be so, but it simplifies + * implementation and testing, and I can't think of any reason + * why it would be desireable. If you can think of one, I'll + * revisit the issue. * * set_initial_size: Boolean flag indicating whether the size of the * initial size of the cache is to be set to the value given in @@ -368,80 +366,80 @@ extern "C" { * * PHDF5 uses several strategies to prevent such inconsistencies in metadata, * all of which use the fact that the same stream of dirty metadata is seen - * by all processes for purposes of synchronization. This is done by + * by all processes for purposes of synchronization. This is done by * having each process count the number of bytes of dirty metadata generated, - * and then running a "sync point" whenever this count exceeds a user + * and then running a "sync point" whenever this count exceeds a user * specified threshold (see dirty_bytes_threshold below). * - * The current metadata write strategy is indicated by the + * The current metadata write strategy is indicated by the * metadata_write_strategy field. The possible values of this field, along * with the associated metadata write strategies are discussed below. * * dirty_bytes_threshold: Threshold of dirty byte creation used to - * synchronize updates between caches. (See above for outline and - * motivation.) + * synchronize updates between caches. (See above for outline and + * motivation.) * - * This value MUST be consistant across all processes accessing the - * file. This field is ignored unless HDF5 has been compiled for - * parallel. + * This value MUST be consistant across all processes accessing the + * file. This field is ignored unless HDF5 has been compiled for + * parallel. * * metadata_write_strategy: Integer field containing a code indicating the - * desired metadata write strategy. The valid values of this field - * are enumerated and discussed below: + * desired metadata write strategy. The valid values of this field + * are enumerated and discussed below: * * - * H5AC_METADATA_WRITE_STRATEGY__PROCESS_0_ONLY: + * H5AC_METADATA_WRITE_STRATEGY__PROCESS_0_ONLY: * - * When metadata_write_strategy is set to this value, only process - * zero is allowed to write dirty metadata to disk. All other - * processes must retain dirty metadata until they are informed at - * a sync point that the dirty metadata in question has been written - * to disk. + * When metadata_write_strategy is set to this value, only process + * zero is allowed to write dirty metadata to disk. All other + * processes must retain dirty metadata until they are informed at + * a sync point that the dirty metadata in question has been written + * to disk. * - * When the sync point is reached (or when there is a user generated - * flush), process zero flushes sufficient entries to bring it into - * complience with its min clean size (or flushes all dirty entries in - * the case of a user generated flush), broad casts the list of - * entries just cleaned to all the other processes, and then exits - * the sync point. + * When the sync point is reached (or when there is a user generated + * flush), process zero flushes sufficient entries to bring it into + * complience with its min clean size (or flushes all dirty entries in + * the case of a user generated flush), broad casts the list of + * entries just cleaned to all the other processes, and then exits + * the sync point. * - * Upon receipt of the broadcast, the other processes mark the indicated - * entries as clean, and leave the sync point as well. + * Upon receipt of the broadcast, the other processes mark the indicated + * entries as clean, and leave the sync point as well. * * - * H5AC_METADATA_WRITE_STRATEGY__DISTRIBUTED: + * H5AC_METADATA_WRITE_STRATEGY__DISTRIBUTED: * - * In the distributed metadata write strategy, process zero still makes - * the decisions as to what entries should be flushed, but the actual - * flushes are distributed across the processes in the computation to - * the extent possible. + * In the distributed metadata write strategy, process zero still makes + * the decisions as to what entries should be flushed, but the actual + * flushes are distributed across the processes in the computation to + * the extent possible. * - * In this strategy, when a sync point is triggered (either by dirty - * metadata creation or manual flush), all processes enter a barrier. + * In this strategy, when a sync point is triggered (either by dirty + * metadata creation or manual flush), all processes enter a barrier. * - * On the other side of the barrier, process 0 constructs an ordered - * list of the entries to be flushed, and then broadcasts this list - * to the caches in all the processes. + * On the other side of the barrier, process 0 constructs an ordered + * list of the entries to be flushed, and then broadcasts this list + * to the caches in all the processes. * - * All processes then scan the list of entries to be flushed, flushing - * some, and marking the rest as clean. The algorithm for this purpose - * ensures that each entry in the list is flushed exactly once, and - * all are marked clean in each cache. + * All processes then scan the list of entries to be flushed, flushing + * some, and marking the rest as clean. The algorithm for this purpose + * ensures that each entry in the list is flushed exactly once, and + * all are marked clean in each cache. * - * Note that in the case of a flush of the cache, no message passing - * is necessary, as all processes have the same list of dirty entries, - * and all of these entries must be flushed. Thus in this case it is - * sufficient for each process to sort its list of dirty entries after - * leaving the initial barrier, and use this list as if it had been - * received from process zero. + * Note that in the case of a flush of the cache, no message passing + * is necessary, as all processes have the same list of dirty entries, + * and all of these entries must be flushed. Thus in this case it is + * sufficient for each process to sort its list of dirty entries after + * leaving the initial barrier, and use this list as if it had been + * received from process zero. + * + * To avoid possible messages from the past/future, all caches must + * wait until all caches are done before leaving the sync point. * - * To avoid possible messages from the past/future, all caches must - * wait until all caches are done before leaving the sync point. - * ****************************************************************************/ -#define H5AC__CURR_CACHE_CONFIG_VERSION 1 -#define H5AC__MAX_TRACE_FILE_NAME_LEN 1024 +#define H5AC__CURR_CACHE_CONFIG_VERSION 1 +#define H5AC__MAX_TRACE_FILE_NAME_LEN 1024 #define H5AC_METADATA_WRITE_STRATEGY__PROCESS_0_ONLY 0 #define H5AC_METADATA_WRITE_STRATEGY__DISTRIBUTED 1 @@ -451,9 +449,9 @@ typedef struct H5AC_cache_config_t /* general configuration fields: */ int version; - hbool_t rpt_fcn_enabled; + hbool_t rpt_fcn_enabled; - hbool_t open_trace_file; + hbool_t open_trace_file; hbool_t close_trace_file; char trace_file_name[H5AC__MAX_TRACE_FILE_NAME_LEN + 1]; @@ -508,6 +506,67 @@ typedef struct H5AC_cache_config_t } H5AC_cache_config_t; +/**************************************************************************** + * + * structure H5AC_cache_image_config_t + * + * H5AC_cache_image_ctl_t is a public structure intended for use in public + * APIs. At least in its initial incarnation, it is a copy of struct + * H5C_cache_image_ctl_t. + * + * The fields of the structure are discussed individually below: + * + * version: Integer field containing the version number of this version + * of the H5C_image_ctl_t structure. Any instance of + * H5C_image_ctl_t passed to the cache must have a known + * version number, or an error will be flagged. + * + * generate_image: Boolean flag indicating whether a cache image should + * be created on file close. + * + * save_resize_status: Boolean flag indicating whether the cache image + * should include the adaptive cache resize configuration and status. + * Note that this field is ignored at present. + * + * entry_ageout: Integer field indicating the maximum number of + * times a prefetched entry can appear in subsequent cache images. + * This field exists to allow the user to avoid the buildup of + * infrequently used entries in long sequences of cache images. + * + * The value of this field must lie in the range + * H5AC__CACHE_IMAGE__ENTRY_AGEOUT__NONE (-1) to + * H5AC__CACHE_IMAGE__ENTRY_AGEOUT__MAX (100). + * + * H5AC__CACHE_IMAGE__ENTRY_AGEOUT__NONE means that no limit + * is imposed on number of times a prefeteched entry can appear + * in subsequent cache images. + * + * A value of 0 prevents prefetched entries from being included + * in cache images. + * + * Positive integers restrict prefetched entries to the specified + * number of appearances. + * + * Note that the number of subsequent cache images that a prefetched + * entry has appeared in is tracked in an 8 bit field. Thus, while + * H5AC__CACHE_IMAGE__ENTRY_AGEOUT__MAX can be increased from its + * current value, any value in excess of 255 will be the functional + * equivalent of H5AC__CACHE_IMAGE__ENTRY_AGEOUT__NONE. + * + ****************************************************************************/ + +#define H5AC__CURR_CACHE_IMAGE_CONFIG_VERSION 1 + +#define H5AC__CACHE_IMAGE__ENTRY_AGEOUT__NONE -1 +#define H5AC__CACHE_IMAGE__ENTRY_AGEOUT__MAX 100 + +typedef struct H5AC_cache_image_config_t { + int version; + hbool_t generate_image; + hbool_t save_resize_status; + int entry_ageout; +} H5AC_cache_image_config_t; + #ifdef __cplusplus } #endif |