Procedure:

Signature:

Parameters:

hid_tfile_id

IN: Identifier of the target file

H5AC_cache_config_t *c=
onfig_ptr

IN: Pointer to the instance of H5AC_c=
ache_config_t containing the desired configuration. The fields =
in this structure can be placed in several categories: &nbsp=
; General configuration &=
nbsp;Increment configuration Decreme=
nt configuration Parallel configurat=
ion Specific fields are described below.

General configuration fields:

intversion

IN: Integer field indicating the the version of =
the H5AC_cache_config_t in use. This field should be=
set to H5AC__CURR_CACHE_CONFIG_VERSION (defined in&=
nbsp;H5ACpublic.h).

hbool_trpt_fcn_enabled

IN: Boolean flag indicating whether the adaptive=
cache resize report function is enabled. This field should almost always b=
e set to FALSE. Since resize algorithm activity is report=
ed via stdout, it MUST be set to FALSE on Windows ma=
chines.

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_topen_trace_File

IN: Boolean field indicating whether the trace_file_name field should be used to open a trace file f=
or the cache.

The trace file is a debuging feature that allows the captur=
e of top level metadata cache requests for purposes of debugging and/or opt=
imization. This field should normally be set to FALSE, as=
trace file collection imposes considerable overhead.

This field shou=
ld only be set to TRUE when the trace_fil=
e_name contains the full path of the desired trace file, and ei=
ther there is no open trace file on the cache, or the close_trac=
e_file field is also TRUE.

The trace fi=
le 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 Th=
e HDF Group, you are on your own.

See the above comments on the&nbsp=
;open_trace_file field. This field should be set to =
FALSE unless there is an open trace file on the cache tha=
t you wish to close.

The trace file feature is unsupported unless use=
d 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 poo=
r performance seen in the field, so as to aid in reproduction in the lab. I=
f you use it absent the direction of The HDF Group, you are on your own.

chartrace_file_name[]

IN: Full path of the trace file to be opened if =
the open_trace_file field is TRUE.=

In the parallel case, an ascii representation of the mpi rank of the pro=
cess will be appended to the file name to yield a unique trace file name fo=
r each process.

The length of the path must not exceed H5A=
C__MAX_TRACE_FILE_NAME_LEN characters.

The trace file fea=
ture is unsupported unless used at the direction of The HDF Group. It is in=
tended 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_tevictions_enabled

IN: A boolean flag indicating whether evictions =
from the metadata cache are enabled. This flag is initially set to TRUE.

In rare circumstances, the raw data throughput requiremen=
ts may be so high that the user wishes to postpone metadata writes so as to=
reserve I/O throughput for raw data. The evictions_enabled field exists to allow this. However, this is an extreme step, and y=
ou have no business doing it unless you have read the User Guide section on=
metadata caching, and have considered all other options carefully.

T=
he evictions_enabled field may not be set to FALSE unless all adaptive cache resizing code is disabled v=
ia the incr_mode, flash_incr_mode, and&=
nbsp;decr_mode fields.

When this flag is set to&nbs=
p;FALSE, the metadata cache will not attempt to evict entries =
to make space for new entries, and thus will grow without bound.

IN: If set_initial_size is TRUE, initial_size must contains the desired initial size in bytes. This value=
must lie in the closed interval [min_size, max_size]. (see below)

doublemin_clean_fraction

IN: This field specifies the minimum fraction of=
the cache that must be kept either clean or empty.

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 Metadata Caching in HDF5 in the collecti=
on =E2=80=9CAdvanced Topics in HDF5.=E2=80=9D

size_tmax_size

IN: Upper bound (in bytes) on the range of value=
s that the adaptive cache resize code can select as the maximum cache size.=

size_tmin_size

IN: Lower bound (in bytes) on the range of value=
s that the adaptive cache resize code can select as the maximum cache size.=

long intepoch_length=

IN: Number of cache accesses between runs of the=
adaptive cache resize code. 50,000 is a good starting number.

Increment configuration fields:

enum H5C_cache_incr_modeinc=
r_mode

IN: Enumerated value indicating the operational =
mode of the automatic cache size increase code. At present, only two values=
are legal:

When the hit rate over an epoch is =
below this threshold and the cache is full, the maximum size of the cache i=
s multiplied by increment (below), and then clipped as necessary to stay wi=
thin max_size, and possibly max_increment.

This field must lie in the=
interval [0.0, 1.0]. 0.8 or 0.9 is a good starting point.

doubleincrement

IN: Factor by which the hit rate threshold cache=
size increment algorithm multiplies the current maximum cache size to obta=
in a tentative new cache size.

The actual cache size increase will be cli=
pped to satisfy the max_size specified in the general configuration, and po=
ssibly max_increment below.

The parameter must be greater than or equ=
al to 1.0 -- 2.0 is a reasonable value.

If you set it to 1.0, you wil=
l effectively disable cache size increases.

hbool_tapply_max_increment<=
/code>

IN: Boolean flag indicating whether an upper lim=
it should be applied to the size of cache size increases.

size_tmax_increment<=
/td>

IN: Maximum number of bytes by which cache size =
can be increased in a single step -- if applicable.

enum H5C_cache_flash_incr_modeflash_incr_mode

IN: Enumerated value indicating the operational =
mode of the flash cache size increase code. At present, only the following =
values are legal:

IN: The factor by which the current maximum cach=
e size is multiplied to obtain the minimum size entry / entry size increase=
which may trigger a flash cache size increase.

At present, this value mu=
st lie in the range [0.1, 1.0].

doubleflash_multiple=

IN: The factor by which the size of the triggeri=
ng entry / entry size increase is multiplied to obtain the initial cache si=
ze increment. This increment may be reduced to reflect existing free space =
in the cache and the max_size field above.

At pres=
ent, this field must lie in the range [0.1, 10.0].

Decrement configuration fields:

enum H5C_cache_decr_modedecr_mode

IN: Enumerated value indicating the operational =
mode of the automatic cache size decrease code. At present, the following v=
alues are legal:

Whe=
n decr_mode is H5C_decr__threshold, and the hit rate over a given epoch exc=
eeds the supplied threshold, the current maximum cache size is multiplied b=
y decrement to obtain a tentative new (and smaller) maximum cache size.

=

When 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 epoc=
h exceeded the supplied threshold.

This field must lie in the interva=
l [0.0, 1.0].

For H5C_incr__threshold, .9995 or .99995 is a good plac=
e to start.

For H5C_decr__age_out_with_threshold, .999 might be more =
useful.

doubledecrement

IN: In the hit rate threshold cache size decreas=
e algorithm, this parameter contains the factor by which the current max ca=
che size is multiplied to produce a tentative new cache size.

The actual =
cache size decrease will be clipped to satisfy the min_size specified in th=
e general configuration, and possibly max_decrement below.

The parame=
ter must be be in the interval [0.0, 1.0].

If you set it to 1.0, you =
will effectively disable cache size decreases. 0.9 is a reasonable starting=
point.

hbool_tapply_max_decrement<=
/code>

IN: Boolean flag indicating whether an upper lim=
it should be applied to the size of cache size decreases.

size_tmax_decrement<=
/td>

IN: Maximum number of bytes by which the maximum=
cache size can be decreased in any single step -- if applicable.

intepochs_before_eviction=
code>

IN: In the ageout based cache size reduction alg=
orithms, this field contains the minimum number of epochs an entry must rem=
ain unaccessed in cache before the cache size reduction algorithm tries to =
evict it. 3 is a reasonable value.

Description:

See the overview of the metadata cache in the special topics section of =
the user manual for details on what is being configured. If you haven't rea=
d and understood that documentation, you really shouldn't be using this API=
call.