6.8.11SET CACHE
Syntax
SET [FILE | DATASET] CACHE {[SLOTS {slots_value | FILE | DEFAULT}] [SIZE {size_value | FILE | DEFAULT}] [PREEMPTION {preemption_value | FILE | DEFAULT}] | DEFAULT}
Description
Set the cache parameter values50 for accessing HDF5 files or datasets. All files or datasets that are subsequently opened or read (through the operations USE FILE or SELECT, respectively) will use the default cache parameter values defined by the HDF5 library or user-defined cache parameter values. These cache parameters are:
- Slots – number of chunk slots in the raw data chunk cache.
- Size – total size of the raw data chunk cache in bytes.
- Preemption – chunk preemption policy.
If neither the keyword FILE nor DATASET is specified, the setting of the cache parameters refers to files by default (optionally, the keyword FILE may be specified to make the purpose of this operation clearer). To explicitly set the cache parameters for datasets, the keyword DATASET must be specified.
Parameter(s)
slots_value – optional integer that specifies the number of chunk slots in the raw data chunk cache for accessing HDF5 files or datasets. If slots_value is specified, it must be equal to or greater than zero (otherwise an error is raised). Due to the hashing strategy, its value should ideally be a prime number. In case the keyword FILE is specified, its value will be as defined in the cache slots parameter upon using (i.e. opening) the file. In case the keyword DEFAULT is specified, its value is 521 (i.e. default value defined by the HDF5 library). In case the keyword SLOTS is not specified, its current value remains intact.
size_value – optional integer that specifies the total size of the raw data chunk cache in bytes for accessing HDF5 files or datasets. If size_value is specified, it must be equal to or greater than zero (otherwise an error is raised). In case the keyword FILE is specified, its value will be as defined in the cache size parameter upon using (i.e. opening) the file. In case the keyword DEFAULT is specified, its value is 1048576 (i.e. 1 MB – default value defined by the HDF5 library). In case the keyword SIZE is not specified, its current value remains intact.
preemption_value – optional float that specifies the chunk preemption policy for accessing HDF5 files or datasets. If preemption_value is specified, it must be between 0 and 1 (otherwise an error is raised). It indicates the weighting according to which chunks that have been fully read or written are penalized when determining which chunks to flush from cache. In case the keyword FILE is specified, its value will be as defined in the cache preemption parameter upon using (i.e. opening) the file. In case the keyword DEFAULT is specified, its value is 0.75 (i.e. default value defined by the HDF5 library). In case the keyword PREEMPTION is not specified, its current value remains intact.
Return
Nothing
Example(s)
# use (i.e. open) an HDF5 file named "my_file0.h5" with cache slots, size, and preemption values of 521, 1048576, and 0.75, respectively (i.e. default values defined by the HDF5 library)
USE FILE my_file0.h5
# set cache slots and preemption values to 2297 and 0.9, respectively (the cache size value remains intact) for subsequent usage (i.e. opening HDF5 files)
SET CACHE SLOTS 2297 PREEMPTION 0.9
# use (i.e. open) an HDF5 file named "my_file1.h5" with cache slots, size, and preemption values of 2297, 1048576, and 0.9, respectively
USE FILE my_file1.h5
# set cache slots, size, and preemption values to 1523, 262144, and 0.6, respectively, for subsequent usage (i.e. opening HDF5 files)
SET FILE CACHE SLOTS 1523 SIZE 262144 PREEMPTION 0.6
# use (i.e. open) an HDF5 file named "my_file2.h5" with cache slots, size, and preemption values of 1523, 262144, and 0.6, respectively
USE FILE my_file2.h5
# set cache size value to 1048576 (i.e. default value defined by the HDF5 library) and preemption value to 0.4 (the cache slots value remains intact) for subsequent usage (i.e. opening HDF5 files)
SET FILE CACHE SIZE DEFAULT PREEMPTION 0.4
# use (i.e. open) an HDF5 file named "my_file3.h5" with cache slots, size, and preemption values of 1523, 1048576, and 0.4, respectively
USE FILE my_file3.h5# select (i.e. read) an HDF5 dataset named "my_dataset0" with cache slots, size, and preemption values of 521, 1048576, and 0.75, respectively (i.e. default values defined by the HDF5 library)
SELECT FROM my_dataset0
# set cache slots and preemption values to 2297 and 0.9, respectively (the cache size value remains intact) for subsequent selection (i.e. reading HDF5 datasets)
SET DATASET CACHE SLOTS 2297 PREEMPTION 0.9
# select (i.e. read) an HDF5 dataset named "my_dataset1" with cache slots, size, and preemption values of 2297, 1048576, and 0.9, respectively
SELECT FROM my_dataset1
# set cache slots, size, and preemption values to 1523, 262144, and 0.6, respectively, for subsequent selection (i.e. reading HDF5 datasets)
SET DATASET CACHE SLOTS 1523 SIZE 262144 PREEMPTION 0.6
# select (i.e. read) an HDF5 dataset named "my_dataset2" with cache slots, size, and preemption values of 1523, 262144, and 0.6, respectively
SELECT FROM my_dataset2
# set cache size value to 1048576 (i.e. default value defined by the HDF5 library) and preemption value to 0.4 (the cache slots value remains intact) for subsequent selection (i.e. reading HDF5 datasets)
SET DATASET CACHE SIZE DEFAULT PREEMPTION 0.4
# select (i.e. read) an HDF5 dataset named "my_dataset3" with cache slots, size, and preemption values of 1523, 1048576, and 0.4, respectively
SELECT FROM my_dataset3
# set cache slots, size, and preemption values to 3089, 2048, and 0.85, respectively, for subsequent usage (i.e. opening HDF5 files)
SET FILE CACHE SLOTS 3089 SIZE 2048 PREEMPTION 0.85
# set cache slots value to 521 (i.e. default value defined by the HDF5 library), size value to 1024, and preemption value to 0.85 (defined by the cache preemption value for HDF5 files) for subsequent selection (i.e. reading HDF5 datasets)
SET DATASET CACHE SLOTS DEFAULT SIZE 1024 PREEMPTION FILE
# select (i.e. read) an HDF5 dataset named "my_dataset4" with cache slots, size, and preemption values of 521, 1024, and 0.85, respectively
SELECT FROM my_dataset4Notes
- By default (i.e. upon initialization of the HDFql library), the cache parameters slots, size, and preemption are set to 521, 1048576, and 0.75, respectively. ↩