EIC code displayed by LXR master/​include/​H5ACpublic.h	Source navigation Diff markup Identifier search General search
	Version: master test Revert   Change

File indexing completed on 2025-04-18 09:16:01

 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
  * Copyright by The HDF Group.                                               *
  * All rights reserved.                                                      *
  *                                                                           *
  * This file is part of HDF5.  The full HDF5 copyright notice, including     *
  * terms governing use, modification, and redistribution, is contained in    *
  * the COPYING file, which can be found at the root of the source code       *
  * distribution tree, or in https://www.hdfgroup.org/licenses.               *
  * If you do not have access to either file, you may request a copy from     *
  * help@hdfgroup.org.                                                        *
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
 /*-------------------------------------------------------------------------
  *
  * Created:             H5ACpublic.h
  *
  * Purpose:             Public include file for cache functions
  *
  *-------------------------------------------------------------------------
  */
 #ifndef H5ACpublic_H
 #define H5ACpublic_H
 
 #include "H5public.h"  /* Generic Functions                        */
 #include "H5Cpublic.h" /* Cache                                    */
 
 /****************************************************************************
  *
  * structure H5AC_cache_config_t
  *
  * H5AC_cache_config_t is a public structure intended for use in public APIs.
  * At least in its initial incarnation, it is basically a copy of struct
  * H5C_auto_size_ctl_t, minus the report_fcn field, and plus the
  * dirty_bytes_threshold field.
  *
  * The report_fcn field is omitted, as including it would require us to
  * make H5C_t structure public.
  *
  * The dirty_bytes_threshold field does not appear in H5C_auto_size_ctl_t,
  * as synchronization between caches on different processes is handled at
  * the H5AC level, not at the level of H5C.  Note however that there is
  * considerable interaction between this value and the other fields in this
  * structure.
  *
  * Similarly, the open_trace_file, close_trace_file, and trace_file_name
  * fields do not appear in H5C_auto_size_ctl_t, as most trace file
  * issues are handled at the H5AC level.  The one exception is storage of
  * the pointer to the trace file, which is handled by H5C.
  *
  * The structure is in H5ACpublic.h as we may wish to allow different
  * configuration options for metadata and raw data caches.
  *
  * The fields of the structure are discussed individually below:
  *
  * version: Integer field containing the version number of this version
  *      of the H5AC_cache_config_t structure.  Any instance of
  *      H5AC_cache_config_t passed to the cache must have a known
  *      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.
  *
  *    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.
  *
  *      *** DEPRECATED *** Use H5Fstart/stop logging functions instead
  *
  *     The trace file is a debugging 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.
  *
  * close_trace_file: Boolean field indicating whether the current trace
  *     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.
  *
  * trace_file_name: Full path of the trace file to be opened if the
  *     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.
  *
  *     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 desirable.  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
  *      the initial_size field.  If set_initial_size is false, the
  *      initial_size field is ignored.
  *
  * initial_size: If enabled, this field contain the size the cache is
  *      to be set to upon receipt of this structure.  Needless to say,
  *      initial_size must lie in the closed interval [min_size, max_size].
  *
  * min_clean_fraction: double in the range 0 to 1 indicating the fraction
  *      of the cache that is to be kept clean.  This field is only used
  *      in parallel mode.  Typical values are 0.1 to 0.5.
  *
  * max_size: Maximum size to which the cache can be adjusted.  The
  *      supplied value must fall in the closed interval
  *      [MIN_MAX_CACHE_SIZE, MAX_MAX_CACHE_SIZE].  Also, max_size must
  *      be greater than or equal to min_size.
  *
  * min_size: Minimum size to which the cache can be adjusted.  The
  *      supplied value must fall in the closed interval
  *      [H5C__MIN_MAX_CACHE_SIZE, H5C__MAX_MAX_CACHE_SIZE].  Also, min_size
  *      must be less than or equal to max_size.
  *
  * epoch_length: Number of accesses on the cache over which to collect
  *      hit rate stats before running the automatic cache resize code,
  *      if it is enabled.
  *
  *      At the end of an epoch, we discard prior hit rate data and start
  *      collecting afresh.  The epoch_length must lie in the closed
  *      interval [H5C__MIN_AR_EPOCH_LENGTH, H5C__MAX_AR_EPOCH_LENGTH].
  *
  *
  * Cache size increase control fields:
  *
  * incr_mode: Instance of the H5C_cache_incr_mode enumerated type whose
  *      value indicates how we determine whether the cache size should be
  *      increased.  At present there are two possible values:
  *
  *      H5C_incr__off:  Don't attempt to increase the size of the cache
  *              automatically.
  *
  *              When this increment mode is selected, the remaining fields
  *              in the cache size increase section ar ignored.
  *
  *      H5C_incr__threshold: Attempt to increase the size of the cache
  *              whenever the average hit rate over the last epoch drops
  *              below the value supplied in the lower_hr_threshold
  *              field.
  *
  *              Note that this attempt will fail if the cache is already
  *              at its maximum size, or if the cache is not already using
  *              all available space.
  *
  *      Note that you must set decr_mode to H5C_incr__off if you
  *      disable metadata cache entry evictions.
  *
  * lower_hr_threshold: Lower hit rate threshold.  If the increment mode
  *      (incr_mode) is H5C_incr__threshold and the hit rate drops below the
  *      value supplied in this field in an epoch, increment the cache size by
  *      size_increment.  Note that cache size may not be incremented above
  *      max_size, and that the increment may be further restricted by the
  *      max_increment field if it is enabled.
  *
  *      When enabled, this field must contain a value in the range [0.0, 1.0].
  *      Depending on the incr_mode selected, it may also have to be less than
  *      upper_hr_threshold.
  *
  * increment:  Double containing the multiplier used to derive the new
  *      cache size from the old if a cache size increment is triggered.
  *      The increment must be greater than 1.0, and should not exceed 2.0.
  *
  *      The new cache size is obtained my multiplying the current max cache
  *      size by the increment, and then clamping to max_size and to stay
  *      within the max_increment as necessary.
  *
  * apply_max_increment:  Boolean flag indicating whether the max_increment
  *      field should be used to limit the maximum cache size increment.
  *
  * max_increment: If enabled by the apply_max_increment field described
  *      above, this field contains the maximum number of bytes by which the
  *      cache size can be increased in a single re-size.
  *
  * flash_incr_mode:  Instance of the H5C_cache_flash_incr_mode enumerated
  *      type whose value indicates whether and by which algorithm we should
  *      make flash increases in the size of the cache to accommodate insertion
  *      of large entries and large increases in the size of a single entry.
  *
  *      The addition of the flash increment mode was occasioned by performance
  *      problems that appear when a local heap is increased to a size in excess
  *      of the current cache size.  While the existing re-size code dealt with
  *      this eventually, performance was very bad for the remainder of the
  *      epoch.
  *
  *      At present, there are two possible values for the flash_incr_mode:
  *
  *      H5C_flash_incr__off:  Don't perform flash increases in the size of
  *              the cache.
  *
  *      H5C_flash_incr__add_space:  Let x be either the size of a newly
  *              newly inserted entry, or the number of bytes by which the
  *              size of an existing entry has been increased.
  *
  *              If
  *                      x > flash_threshold * current max cache size,
  *
  *              increase the current maximum cache size by x * flash_multiple
  *              less any free space in the cache, and star a new epoch.  For
  *              now at least, pay no attention to the maximum increment.
  *
  *      In both of the above cases, the flash increment pays no attention to
  *      the maximum increment (at least in this first incarnation), but DOES
  *      stay within max_size.
  *
  *      With a little thought, it should be obvious that the above flash
  *      cache size increase algorithm is not sufficient for all circumstances
  *      -- for example, suppose the user round robins through
  *      (1/flash_threshold) +1 groups, adding one data set to each on each
  *      pass.  Then all will increase in size at about the same time, requiring
  *      the max cache size to at least double to maintain acceptable
  *      performance, however the above flash increment algorithm will not be
  *      triggered.
  *
  *      Hopefully, the add space algorithms detailed above will be sufficient
  *      for the performance problems encountered to date.  However, we should
  *      expect to revisit the issue.
  *
  * flash_multiple: Double containing the multiple described above in the
  *      H5C_flash_incr__add_space section of the discussion of the
  *      flash_incr_mode section.  This field is ignored unless flash_incr_mode
  *      is H5C_flash_incr__add_space.
  *
  * flash_threshold: Double containing the factor by which current max cache
  *      size is multiplied to obtain the size threshold for the add_space flash
  *      increment algorithm.  The field is ignored unless flash_incr_mode is
  *      H5C_flash_incr__add_space.
  *
  *
  * Cache size decrease control fields:
  *
  * decr_mode: Instance of the H5C_cache_decr_mode enumerated type whose
  *      value indicates how we determine whether the cache size should be
  *      decreased.  At present there are four possibilities.
  *
  *      H5C_decr__off:  Don't attempt to decrease the size of the cache
  *              automatically.
  *
  *              When this increment mode is selected, the remaining fields
  *              in the cache size decrease section are ignored.
  *
  *      H5C_decr__threshold: Attempt to decrease the size of the cache
  *              whenever the average hit rate over the last epoch rises
  *              above the value supplied in the upper_hr_threshold
  *              field.
  *
  *      H5C_decr__age_out:  At the end of each epoch, search the cache for
  *              entries that have not been accessed for at least the number
  *              of epochs specified in the epochs_before_eviction field, and
  *              evict these entries.  Conceptually, the maximum cache size
  *              is then decreased to match the new actual cache size.  However,
  *              this reduction may be modified by the min_size, the
  *              max_decrement, and/or the empty_reserve.
  *
  *      H5C_decr__age_out_with_threshold:  Same as age_out, but we only
  *              attempt to reduce the cache size when the hit rate observed
  *              over the last epoch exceeds the value provided in the
  *              upper_hr_threshold field.
  *
  *      Note that you must set decr_mode to H5C_decr__off if you
  *      disable metadata cache entry evictions.
  *
  * upper_hr_threshold: Upper hit rate threshold.  The use of this field
  *      varies according to the current decr_mode:
  *
  *      H5C_decr__off or H5C_decr__age_out:  The value of this field is
  *              ignored.
  *
  *      H5C_decr__threshold:  If the hit rate exceeds this threshold in any
  *              epoch, attempt to decrement the cache size by size_decrement.
  *
  *              Note that cache size may not be decremented below min_size.
  *
  *              Note also that if the upper_threshold is 1.0, the cache size
  *              will never be reduced.
  *
  *      H5C_decr__age_out_with_threshold:  If the hit rate exceeds this
  *              threshold in any epoch, attempt to reduce the cache size
  *              by evicting entries that have not been accessed for more
  *              than the specified number of epochs.
  *
  * decrement: This field is only used when the decr_mode is
  *      H5C_decr__threshold.
  *
  *      The field is a double containing the multiplier used to derive the
  *      new cache size from the old if a cache size decrement is triggered.
  *      The decrement must be in the range 0.0 (in which case the cache will
  *      try to contract to its minimum size) to 1.0 (in which case the
  *      cache will never shrink).
  *
  * apply_max_decrement:  Boolean flag used to determine whether decrements
  *      in cache size are to be limited by the max_decrement field.
  *
  * max_decrement: Maximum number of bytes by which the cache size can be
  *      decreased in a single re-size.  Note that decrements may also be
  *      restricted by the min_size of the cache, and (in age out modes) by
  *      the empty_reserve field.
  *
  * epochs_before_eviction:  Integer field used in H5C_decr__age_out and
  *      H5C_decr__age_out_with_threshold decrement modes.
  *
  *      This field contains the number of epochs an entry must remain
  *      unaccessed before it is evicted in an attempt to reduce the
  *      cache size.  If applicable, this field must lie in the range
  *      [1, H5C__MAX_EPOCH_MARKERS].
  *
  * apply_empty_reserve:  Boolean field controlling whether the empty_reserve
  *      field is to be used in computing the new cache size when the
  *      decr_mode is H5C_decr__age_out or H5C_decr__age_out_with_threshold.
  *
  * empty_reserve:  To avoid a constant racheting down of cache size by small
  *      amounts in the H5C_decr__age_out and H5C_decr__age_out_with_threshold
  *      modes, this field allows one to require that any cache size
  *      reductions leave the specified fraction of unused space in the cache.
  *
  *      The value of this field must be in the range [0.0, 1.0].  I would
  *      expect typical values to be in the range of 0.01 to 0.1.
  *
  *
  * Parallel Configuration Fields:
  *
  * In PHDF5, all operations that modify metadata must be executed collectively.
  *
  * We used to think that this was enough to ensure consistency across the
  * metadata caches, but since we allow processes to read metadata individually,
  * the order of dirty entries in the LRU list can vary across processes,
  * which can result in inconsistencies between the caches.
  *
  * 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
  * having each process count the number of bytes of dirty metadata generated,
  * 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
  * 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.)
  *
  *    This value MUST be consistent 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:
  *
  *
  *    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 the sync point is reached (or when there is a user generated
  *    flush), process zero flushes sufficient entries to bring it into
  *    compliance 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.
  *
  *
  *    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 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.
  *
  *    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.
  *
  *    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_METADATA_WRITE_STRATEGY__PROCESS_0_ONLY 0
 #define H5AC_METADATA_WRITE_STRATEGY__DISTRIBUTED    1
 
 /**
  * H5AC_cache_config_t is a public structure intended for use in public APIs.
  * At least in its initial incarnation, it is basically a copy of \c struct
  * \c H5C_auto_size_ctl_t, minus the \c report_fcn field, and plus the
  * \c dirty_bytes_threshold field.
  *
  * The \c report_fcn field is omitted, as including it would require us to make
  * \c H5C_t structure public.
  *
  * The \c dirty_bytes_threshold field does not appear in \c H5C_auto_size_ctl_t,
  * as synchronization between caches on different processes is handled at the \c
  * H5AC level, not at the level of \c H5C.  Note however that there is
  * considerable interaction between this value and the other fields in this
  * structure.
  *
  * Similarly, the \c open_trace_file, \c close_trace_file, and \c
  * trace_file_name fields do not appear in \c H5C_auto_size_ctl_t, as most trace
  * file issues are handled at the \c H5AC level.  The one exception is storage
  * of the pointer to the trace file, which is handled by \c H5C.
  *
  * The structure is in H5ACpublic.h as we may wish to allow different
  * configuration options for metadata and raw data caches.
  */
 
 //! <!-- [H5AC_cache_config_t_snip] -->
 typedef struct H5AC_cache_config_t {
     /* general configuration fields: */
     //! <!-- [H5AC_cache_config_t_general_snip] -->
     int version;
     /**< Integer field indicating the version of the H5AC_cache_config_t
      * in use. This field should be set to #H5AC__CURR_CACHE_CONFIG_VERSION
      * (defined in H5ACpublic.h). */
 
     hbool_t rpt_fcn_enabled;
     /**< Boolean flag indicating whether the adaptive cache resize report
      * function is enabled. This field should almost always be set to disabled
      * (0). Since resize algorithm activity is reported via stdout, it MUST be
      * set to disabled (0) on Windows machines.\n
      * The report function is not supported code, and can be expected to change
      * between versions of the library. Use it at your own risk. */
 
     hbool_t open_trace_file;
     /**< Boolean field indicating whether the
      * \ref H5AC_cache_config_t.trace_file_name "trace_file_name"
      * field should be used to open a trace file for the cache.\n
      * The trace file is a debugging feature that allows the capture
      * of top level metadata cache requests for purposes of debugging
      * and/or optimization. This field should normally be set to 0, as
      * trace file collection imposes considerable overhead.\n
      * This field should only be set to 1 when the
      * \ref H5AC_cache_config_t.trace_file_name "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
      * \ref H5AC_cache_config_t.close_trace_file "close_trace_file"
      * field is also 1.\n
      * The trace file feature is unsupported unless used at the
      * direction of The HDF Group. It is intended to allow The HDF
      * Group to collect a trace of cache activity in cases of occult
      * failures and/or poor performance seen in the field, so as to aid
      * in reproduction in the lab. If you use it absent the direction
      * of The HDF Group, you are on your own. */
 
     hbool_t close_trace_file;
     /**< Boolean field indicating whether the current trace file
      *(if any) should be closed.\n
      * See the above comments on the \ref H5AC_cache_config_t.open_trace_file
      * "open_trace_file" field. This field should be set to 0 unless there is
      * an open trace file on the cache that you wish to close.\n
      * The trace file feature is unsupported unless used at the direction of
      * The HDF Group. It is intended to allow The HDF Group to collect a trace
      * of cache activity in cases of occult failures and/or poor performance
      * seen in the field, so as to aid in reproduction in the lab. If you use
      * it absent the direction of The HDF Group, you are on your own. */
 
     char trace_file_name[H5AC__MAX_TRACE_FILE_NAME_LEN + 1];
     /**< Full path of the trace file to be opened if the
      * \ref H5AC_cache_config_t.open_trace_file "open_trace_file" field is set
      * to 1.\n
      * 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.\n
      * The length of the path must not exceed #H5AC__MAX_TRACE_FILE_NAME_LEN
      * characters.\n
      * The trace file feature is unsupported unless used at the direction of
      * The HDF Group. It is intended to allow The HDF Group to collect a trace
      * of cache activity in cases of occult failures and/or poor performance
      * seen in the field, so as to aid in reproduction in the lab. If you use
      * it absent the direction of The HDF Group, you are on your own. */
 
     hbool_t evictions_enabled;
     /**< A boolean flag indicating whether evictions from the metadata cache
      * are enabled. This flag is initially set to enabled (1).\n
      * In rare circumstances, the raw data throughput quirements may be so high
      * that the user wishes to postpone metadata writes so as to reserve I/O
      * throughput for raw data. The \p evictions_enabled field exists to allow
      * this. However, this is an extreme step, and you have no business doing
      * it unless you have read the User Guide section on metadata caching, and
      * have considered all other options carefully.\n
      * The \p evictions_enabled field may not be set to disabled (0)
      * unless all adaptive cache resizing code is disabled via the
      * \ref H5AC_cache_config_t.incr_mode "incr_mode",
      * \ref H5AC_cache_config_t.flash_incr_mode "flash_incr_mode",
      * \ref H5AC_cache_config_t.decr_mode "decr_mode" fields.\n
      * When this flag is set to disabled (\c 0), the metadata cache will not
      * attempt to evict entries to make space for new entries, and thus will
      * grow without bound.\n
      * Evictions will be re-enabled when this field is set back to \c 1.
      * This should be done as soon as possible. */
 
     hbool_t set_initial_size;
     /**< Boolean flag indicating whether the cache should be created
      * with a user specified initial size. */
 
     size_t initial_size;
     /**< If \ref H5AC_cache_config_t.set_initial_size "set_initial_size"
      * is set to 1, \p initial_size must contain he desired initial size in
      * bytes. This value must lie in the closed interval
      * [ \p min_size, \p max_size ]. (see below) */
 
     double min_clean_fraction;
     /**< This field specifies the minimum fraction of the cache
      * that must be kept either clean or empty.\n
      * The value must lie in the interval [0.0, 1.0]. 0.01 is a good place to
      * start in the serial case. In the parallel case, a larger value is needed
      * -- see the overview of the metadata cache in the
      * “Metadata Caching in HDF5” section of the -- <em>\ref UG</em>
      * for details. */
 
     size_t max_size;
     /**< Upper bound (in bytes) on the range of values that the
      * adaptive cache resize code can select as the maximum cache size. */
 
     size_t min_size;
     /**< Lower bound (in bytes) on the range of values that the
      * adaptive cache resize code can select as the minimum cache * size. */
 
     long int epoch_length;
     /**< Number of cache accesses between runs of the adaptive cache resize
      * code. 50,000 is a good starting number. */
     //! <!-- [H5AC_cache_config_t_general_snip] -->
 
     /* size increase control fields: */
     //! <!-- [H5AC_cache_config_t_incr_snip] -->
     enum H5C_cache_incr_mode incr_mode;
     /**< Enumerated value indicating the operational mode of the automatic
      * cache size increase code. At present, only two values listed in
      * #H5C_cache_incr_mode are legal. */
 
     double lower_hr_threshold;
     /**< Hit rate threshold used by the hit rate threshold cache size
      * increment algorithm.\n
      * When the hit rate over an epoch is below this threshold and the cache
      * is full, the maximum size of the cache is multiplied by increment
      * (below), and then clipped as necessary to stay within \p max_size, and
      * possibly \p max_increment.\n
      * This field must lie in the interval [0.0, 1.0]. 0.8 or 0.9 is a good
      * place to start. */
 
     double increment;
     /**< Factor by which the hit rate threshold cache size increment
      * algorithm multiplies the current cache max size to obtain a tentative
      * new cache size.\n
      * The actual cache size increase will be clipped to satisfy the \p max_size
      * specified in the general configuration, and possibly max_increment
      * below.\n
      * The parameter must be greater than or equal to 1.0 -- 2.0 is a reasonable
      * value.\n
      * If you set it to 1.0, you will effectively disable cache size increases.
      */
 
     hbool_t apply_max_increment;
     /**< Boolean flag indicating whether an upper limit should be applied to
      * the size of cache size increases. */
 
     size_t max_increment;
     /**< Maximum number of bytes by which cache size can be increased in a
      * single step -- if applicable. */
 
     enum H5C_cache_flash_incr_mode flash_incr_mode;
     /**< Enumerated value indicating the operational mode of the flash cache
      * size increase code. At present, only two listed  values in
      * #H5C_cache_flash_incr_mode are legal.*/
 
     double flash_multiple;
     /**< The factor by which the size of the triggering entry / entry size
      * increase is multiplied to obtain the initial cache size increment. This
      * increment may be reduced to reflect existing free space in the cache and
      * the \p max_size field above.\n
      * The parameter must lie in the interval [0.0, 1.0]. 0.1 or 0.05 is a good
      * place to start.\n
      * At present, this field must lie in the range [0.1, 10.0]. */
 
     double flash_threshold;
     /**< The factor by which the current maximum cache size is multiplied to
      * obtain the minimum size entry / entry size increase which may trigger a
      * flash cache size increase. \n
      * At present, this value must lie in the range [0.1, 1.0]. */
     //! <!-- [H5AC_cache_config_t_incr_snip] -->
 
     /* size decrease control fields: */
     //! <!-- [H5AC_cache_config_t_decr_snip] -->
     enum H5C_cache_decr_mode decr_mode;
     /**< Enumerated value indicating the operational mode of the tomatic
      * cache size decrease code. At present, the values listed in
      * #H5C_cache_decr_mode are legal.*/
 
     double upper_hr_threshold;
     /**< Hit rate threshold for the hit rate threshold and ageout with hit
      * rate threshold cache size decrement algorithms.\n
      * When \p decr_mode is #H5C_decr__threshold, and the hit rate over a given
      * epoch exceeds the supplied threshold, the current maximum cache
      * size is multiplied by decrement to obtain a tentative new (and smaller)
      * maximum cache size.\n
      * When \p decr_mode is #H5C_decr__age_out_with_threshold, there is
      * no attempt to find and evict aged out entries unless the hit rate in
      * the previous epoch exceeded the supplied threshold.\n
      * This field must lie in the interval [0.0, 1.0].\n
      * For #H5C_incr__threshold, .9995 or .99995 is a good place to start.\n
      * For #H5C_decr__age_out_with_threshold, .999 might be more useful.*/
 
     double decrement;
     /**< In the hit rate threshold cache size decrease algorithm, this
      * parameter contains the factor by which the current max cache size is
      * multiplied to produce a tentative new cache size.\n
      * The actual cache size decrease will be clipped to satisfy the
      * \ref H5AC_cache_config_t.min_size "min_size" specified in the general
      * configuration, and possibly \ref H5AC_cache_config_t.max_decrement
      * "max_decrement".\n
      * The parameter must be be in the interval [0.0, 1.0].\n
      * If you set it to 1.0, you will effectively
      * disable cache size decreases. 0.9 is a reasonable starting point. */
 
     hbool_t apply_max_decrement;
     /**< Boolean flag indicating ether an upper limit should be applied to
      * the size of cache size decreases. */
 
     size_t max_decrement;
     /**< Maximum number of bytes by which the maximum cache size can be
      * decreased in any single step -- if applicable.*/
 
     int epochs_before_eviction;
     /**< In the ageout based cache size reduction algorithms, this field
      * contains the minimum number of epochs an entry must remain unaccessed in
      * cache before the cache size reduction algorithm tries to evict it. 3 is a
      * reasonable value. */
 
     hbool_t apply_empty_reserve;
     /**< Boolean flag indicating whether the ageout based decrement
      * algorithms will maintain a empty reserve when decreasing cache size. */
 
     double empty_reserve;
     /**< Empty reserve as a fraction maximum cache size if applicable.\n When
      * so directed, the ageout based algorithms will not decrease the maximum
      * cache size unless the empty reserve can be met.\n The parameter must lie
      * in the interval [0.0, 1.0]. 0.1 or 0.05 is a good place to start. */
     //! <!-- [H5AC_cache_config_t_decr_snip] -->
 
     /* parallel configuration fields: */
     //! <!-- [H5AC_cache_config_t_parallel_snip] -->
     size_t dirty_bytes_threshold;
     /**< Threshold number of bytes of dirty metadata generation for
      * triggering synchronizations of the metadata caches serving the target
      * file in the parallel case.\n Synchronization occurs whenever the number
      * of bytes of dirty metadata created since the last synchronization exceeds
      * this limit.\n This field only applies to the parallel case. While it is
      * ignored elsewhere, it can still draw a value out of bounds error.\n It
      * must be consistent across all caches on any given file.\n By default,
      * this field is set to 256 KB. It shouldn't be more than half the current
      * max cache size times the min clean fraction. */
 
     int metadata_write_strategy;
     /**< Desired metadata write strategy. The valid values for this field
      * are:\n #H5AC_METADATA_WRITE_STRATEGY__PROCESS_0_ONLY: Specifies the only
      * process zero is allowed to write dirty metadata to disk.\n
      * #H5AC_METADATA_WRITE_STRATEGY__DISTRIBUTED: Specifies that 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.\n The src/H5ACpublic.h include file in the HDF5
      * library has detailed information on each strategy. */
     //! <!-- [H5AC_cache_config_t_parallel_snip] -->
 } H5AC_cache_config_t;
 //! <!-- [H5AC_cache_config_t_snip] -->
 
 #define H5AC__CURR_CACHE_IMAGE_CONFIG_VERSION 1
 
 #define H5AC__CACHE_IMAGE__ENTRY_AGEOUT__NONE -1
 #define H5AC__CACHE_IMAGE__ENTRY_AGEOUT__MAX  100
 
 //! <!-- [H5AC_cache_image_config_t_snip] -->
 /**
  * H5AC_cache_image_config_t is a public structure intended for use in public
  * APIs.  At least in its initial incarnation, it is a copy of \c struct \c
  * H5C_cache_image_ctl_t.
  */
 
 typedef struct H5AC_cache_image_config_t {
     int version;
     /**< Integer field containing the version number of this version of the \c
      *  H5C_image_ctl_t structure.  Any instance of \c H5C_image_ctl_t passed
      *  to the cache must have a known version number, or an error will be
      *  flagged.
      */
     hbool_t generate_image;
     /**< Boolean flag indicating whether a cache image should be created on file
      *   close.
      */
     hbool_t 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.
      */
     int 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 \ref
      *   H5AC__CACHE_IMAGE__ENTRY_AGEOUT__NONE (-1) to \ref
      *   H5AC__CACHE_IMAGE__ENTRY_AGEOUT__MAX (100).
      *
      *   \ref H5AC__CACHE_IMAGE__ENTRY_AGEOUT__NONE means that no limit is
      *   imposed on number of times a prefetched 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 \ref
      *   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
      *   \ref H5AC__CACHE_IMAGE__ENTRY_AGEOUT__NONE.
      */
 } H5AC_cache_image_config_t;
 
 //! <!-- [H5AC_cache_image_config_t_snip] -->
 
 #endif

This page was automatically generated by the 2.3.7 LXR engine. The LXR team