onetime_do {onetime}

Run code only once

Description

When first called, onetime_do() evaluates an expression. It then creates a lockfile recording a unique ID which will prevent the expression being run on subsequent calls.

Usage

onetime_do(
  expr,
  id = deprecate_calling_package(),
  path = default_lockfile_dir(),
  expiry = NULL,
  default = NULL,
  without_permission = c("warn", "run", "stop", "pass", "ask")
)

Arguments

expr

The code to evaluate. An R statement or expression() object.

id

Unique ID string. If this is unset, the name of the calling package will be used. Since onetime 0.2.0, not setting id is deprecated.

path

Directory to store lockfiles. The default uses a unique directory corresponding to the calling package, beneath rappdirs::user_config_dir(). Normally you should leave this as the default.

expiry

difftime() or e.g. lubridate::duration() object. After this length of time, code will be run again.

default

Value to return if expr was not executed.

without_permission

Character string. What to do if the user hasn't given permission to store files? "warn" runs the action with an extra warning; "run" runs the action with no warning; "pass" does nothing and returns the default; "stop" throws an error; "ask" asks for permission using check_ok_to_store(), and returns the default if it is not granted.

Details

onetime_do() is the engine used by other onetime functions.

Calls are identified by id. If you use the same value of id across different calls to onetime functions, only the first call will get made.

The default path, where lockfiles are stored, is in a per-package directory beneath rappdirs::user_config_dir(). To use a different subdirectory within the onetime base directory, set path = onetime_dir("dirname").

End users can also set options(onetime.dir) to change the base directory. Package authors should only set this option locally within package functions, if at all.

If the call gives an error, the lockfile is still written.

expiry is backward-looking. That is, expiry is used at check time to see if the lockfile was written after Sys.time() - expiry. It is not used when the lockfile is created. So, you should set expiry to the same value whenever you call onetime_do(). See the example.

Value

onetime_do() invisibly returns the value of expr, or default if expr was not run because it had been run already.

Examples

oo <- options(onetime.dir = tempdir(check = TRUE))
id <- sample(10000L, 1L)

for (n in 1:3) {
  onetime_do(print("printed once"), id = id)
}

# expiry is "backward-looking":
id2 <- sample(10000L, 1L)
expiry <- as.difftime(1, units = "secs")
onetime_do(print("Expires quickly, right?"), id = id2, expiry = expiry)
Sys.sleep(2)
onetime_do(print("This won't be shown..."), id = id2)
onetime_do(print("... but this will"), id = id2, expiry = expiry)


onetime_reset(id = id)
onetime_reset(id = id2)
options(oo)