h5_FileLocking: Test and set file locking for HDF5

In grimbough/rhdf5: R Interface to HDF5

Test and set file locking for HDF5

Description

HDF5 1.10 uses file locking by default. On some file systems this is not available, and the HDF5 library will throw an error if the user attempts to create or access a file located on such a file system. These functions help identify if file locking is available without throwing an error, and allow the locking to be disabled for the duration of the R session if needed.

Usage

h5testFileLocking(location)

h5disableFileLocking()

h5enableFileLocking()

Arguments

location

The name of a directory or file to test. If an existing directory is provided a temporary file will be created in this folder. If non-existant location is provided a file with the name will be created, tested for file locking, and then removed. Providing an existing file will result in an error.

Details

h5testFileLocking will create a temporary file and then attempt to apply a file lock using the appropriate function within the HDF5 library. The success or failure of the locking is then recorded and the temporary file removed. Even relatively low level functions such as H5Fcreate will fail inelegantly if file locking fails.

h5disableFileLocking will set the environment variable RHDF5_USE_FILE_LOCKING=FALSE, which is the recommended was to disable this behaviour if file locking is not supported. This will only persist within the current R session. You can set the environment variable outside of R if this is a more general issue on your system.

h5enableFileLocking will unset the RHDF5_USE_FILE_LOCKING environment variable.

More discussion of HDF5's use of file locking can be found online e.g. https://forum.hdfgroup.org/t/hdf5-1-10-0-and-flock/3761/4 or https://forum.hdfgroup.org/t/hdf5-files-on-nfs/3985/5

Value

h5testFileLocking returns TRUE if a file can be successfully locked at the specified location, or FALSE otherwise.

h5disableFileLocking and h5enableFileLocking set are called for the side effect of setting or unsetting the environment variable HDF5_USE_FILE_LOCKING and do not return anything.

Author(s)

Mike Smith

Examples

## either a file name or directory can be tested
file <- tempfile()
dir <- tempdir()

h5testFileLocking(dir)
h5testFileLocking(file)

## we can check for file locking, and disable if needed
if( !h5testFileLocking(dir) ) {
  h5disableFileLocking()
}

grimbough/rhdf5 documentation built on Sept. 14, 2024, 8:41 a.m.