touchDirectory: Touch a versioned directory

In LTLA/dir.expiry: Managing Expiration for Cache Directories

Touch a versioned directory

Description

Touch a versioned directory to indicate that it has been successfully accessed in the recent past.

Usage

touchDirectory(path, date = Sys.Date(), force = FALSE)

Arguments

path	String containing the path to a versioned directory. The dirname should be the package cache while the basename should be a version number.
date	A Date object containing the current date. Only provided for testing.
force	Logical scalar indicating whether to forcibly update the access date for path.

Details

This function is used to update the last-accessed timestamp for a particular versioned directory. The timestamp is stored in a *_dir.expiry stub file inside path, and is checked by clearDirectories to determine whether the directory is old enough for deletion. We use an explicit timestamp instead of relying on POSIX access times as the latter may not be reliable indicators of genuine access (e.g., during filesystem scans for viruses or to create backups) or may be turned off altogether for performance reasons. The touchDirectory function should be used in the following manner to ensure thread safety:

1. The user should first call lockDirectory(path) before calling touchDirectory(path). This ensures that another process calling clearDirectories does not delete path while its access time is being updated.

2. The caller should then perform the desired operations on path. This may be a read-only operation if the V lock is a shared lock or a read/write operation for an exclusive lock.

3. Once the operation has completed successfully, the caller should call touchDirectory(path). This ensures that the most recent timestamp is recorded, especially for long-running operations. Multiple processes may safely call touchDirectory(path) when the V lock is shared.

4. Finally, the user should call unlockDirectory(path). This is typically wrapped in an on.exit to ensure that the locks are removed.

For a given path and version, this function only modifies the files on its first call. All subsequent calls with the same two arguments, in the same R session, and on the same day will have no effect. This avoids unnecessary filesystem writes and locks when this function is repeatedly called. Advanced users can force an update by setting force=TRUE.

Value

The <version>_dir.expiry stub file within path is updated/created with the current date. A NULL is invisibly returned.

Author(s)

Aaron Lun

See Also

lockDirectory, which should always be called before this function.

Examples

# Creating the package cache.
cache.dir <- tempfile(pattern="expired_demo")
dir.create(cache.dir)

# Creating the versioned subdirectory.
version <- package_version("1.11.0")
version.dir <- file.path(cache.dir, version)
lck <- lockDirectory(version.dir)
dir.create(version.dir)

# Setting the last access time.
touchDirectory(version.dir)
list.files(cache.dir)
readLines(file.path(cache.dir, "1.11.0_dir.expiry"))

# Making sure we unlock it afterwards.
unlockDirectory(lck)

LTLA/dir.expiry documentation built on Oct. 20, 2024, 8:09 a.m.