Reuse the result of a computation — shared

Captures command without evaluating it. A computation key combines its code, statically discovered referenced values and helpers, package identities, context, and seed. A hit restores the result; a miss evaluates the command under a lock for that key and publishes the complete successful result.

Usage

shared_run(
  command,
  cache,
  format = "rds",
  context = list(),
  seed = 0L,
  packages = character(),
  owner = shared_owner(),
  localize = FALSE
)

Arguments

command: R expression to evaluate only on a cache miss.
cache: Configuration from shared_cache().
format: "rds" for self-contained R values or "file" for paths to files or directories created below shared_path(). All sidecar files in that directory are retained together, preserving their names and structure.
context: Explicit values for relevant state outside ordinary R dependency analysis: for example an immutable container image ID, external program version, database snapshot, sample label, or deliberate cache generation.
seed: Nonnegative integer mixed into the computation identity. Random numbers use a key-derived seed with L'Ecuyer-CMRG, Inversion, and Rejection. The caller's RNG state is restored. Independent random replicates must have distinct input or context values, or a different seed.
packages: Additional installed packages whose versions should enter the key. Namespaced calls and functions' namespaces are discovered automatically.
owner: Retention owner. Defaults to the current targets store, or the working directory for standalone calls. References are cumulative until explicitly released with shared_release(). Not part of the action key.
localize: Copy file outputs to disposable cache-local export staging. Used by the target factory for nonlocal repositories which may move inputs. Return the bundle directory or explicitly return every sidecar in this mode.

Value

The R value or the cache-owned paths returned by the computation.

Details

Use deterministic computations with explicit inputs. Static code analysis cannot discover dynamic lookups, changing network/database state, options, environment variables, or external executables. Declare those dependencies in context. Plain character paths are ordinary R values: use shared_file() to identify a file by its contents. That declaration assumes output semantics do not depend on the file's physical location.

Cache entries and returned files are immutable. Do not modify them in place. Use format = "file" for file artifacts; an RDS object containing paths to a temporary or project directory does not preserve those files. This package never rewrites arbitrary path strings inside R objects.

A condition of class tarshare_event is emitted as a message for each hit or computation. Its event and key fields are available to calling handlers.

Examples

cache <- shared_cache(tempfile("shared-cache-"))
x <- 1:10
shared_run(mean(x), cache)
#> tarshare compute ce906e5e2ff3
#> [1] 5.5
shared_run(mean(x), cache)
#> tarshare hit ce906e5e2ff3
#> [1] 5.5
shared_run({
  path <- shared_path("summary.txt")
  writeLines(as.character(mean(x)), path)
  path
}, cache, format = "file")
#> tarshare compute f4222b7dd8e9
#> [1] "/tmp/Rtmp7EqBfI/shared-cache-1a8943d09b1b/objects/569e5b5399e1f7d01255596890bc672571795b8717fce1c06bf53851c9ba460c/files/summary.txt"