Declare a target backed by a shared computation cache

These factories create ordinary targets whose commands use shared_run(). targets still schedules the work, tracks dependencies, and owns each pipeline's metadata. An existing shared result avoids evaluating the original command after the target is dispatched.

Usage

tar_shared(
  name,
  command,
  cache,
  pattern = NULL,
  format = c("rds", "file"),
  context = list(),
  branch_context = list(),
  seed = 0L,
  packages = targets::tar_option_get("packages"),
  ...
)

tar_shared_raw(
  name,
  command,
  cache,
  pattern = NULL,
  format = c("rds", "file"),
  context = list(),
  branch_context = quote(list()),
  seed = 0L,
  packages = targets::tar_option_get("packages"),
  ...
)

Arguments

name: Target name. Supply an unquoted symbol to tar_shared() and a character string to tar_shared_raw().
command: R command. It is captured without evaluation by tar_shared(). Supply an expression object, usually made with quote(), to tar_shared_raw().
cache: A shared_cache() object, evaluated when the target is declared.
pattern: Dynamic branching pattern, captured by tar_shared(). Supply an expression object or NULL to tar_shared_raw().
format: Either "rds" for an R value or "file" for files created with shared_path(). Cached files remain owned by the shared cache; downstream commands must treat them as immutable.
context: External context, evaluated once when the target is declared. Use shared_context() to snapshot options, resources and provider identities. Its canonical identity is embedded in the target command and the shared key. For the raw factory, supply a value, not a quoted expression.
branch_context: Target-derived context, captured as an expression. Use this for upstream targets and dynamic branch values, not ambient state.
seed: Seed input for shared_run(). This also remains a runtime expression in tar_shared(); supply an expression object or literal value to tar_shared_raw(). The effective RNG stream is derived from the shared computation key, independently of the target name. Give independent stochastic replicates distinct seeds or replicate identities in context.
packages: Character vector of packages to load for this target and include in its execution identity. Evaluated when the target is declared.
...: Other arguments to targets::tar_target_raw(), such as iteration, cue, memory, deployment, or a public CAS repository. Nonlocal file outputs are copied before repository upload; return the whole bundle directory or every sidecar. Overrides of deps and string are unsupported: ordinary dependency detection and command invalidation remain enabled.

Value

A target definition object to include in a targets pipeline.

Details

The command, branch context, and seed are embedded as unquoted expressions in the generated command. This preserves the ordinary static dependency analysis of targets, including dynamic branch inputs. No target metadata is read or modified by these factories.

Only the declared computation is shared. Operations which observe the target name, pipeline directory, time, or other external state need appropriate explicit context; they are not made independent of that state by this factory. See shared_run() for the cache identity contract.

Examples

cache <- shared_cache(tempfile("shared-cache-"))
tar_shared(result, sum(data), cache)
#> <tar_stem> 
#>   name: result 
#>   description:  
#>   command:
#>     tarshare::shared_run(command = sum(data), cache = list(
#>         path = "/tmp/Rtmp7EqBfI/shared-cache-1a89777bbce2", verify = TRUE, 
#>         timeout = Inf, visibility_timeout = 0, poll_interval = 0.05), 
#>         format = "rds", context = list(static = "6673d7954c1728d777660559e70bff8c99c0acb5879d3737a36c919570a005ce", 
#>             branch = list()), seed = 0L, packages = c("tarshare", 
#>         "stats", "graphics", "grDevices", "utils", "datasets", "methods", 
#>         "base"), owner = tarshare::shared_owner(store = targets::tar_path_store()), 
#>         localize = FALSE) 
#>   format: rds 
#>   repository: local 
#>   iteration method: vector 
#>   error mode: stop 
#>   memory mode: auto 
#>   storage mode: worker 
#>   retrieval mode: auto 
#>   deployment mode: worker 
#>   priority: 0 
#>   resources:
#>     list() 
#>   cue:
#>     seed: TRUE
#>     file: TRUE
#>     iteration: TRUE
#>     repository: TRUE
#>     format: TRUE
#>     depend: TRUE
#>     command: TRUE
#>     mode: thorough 
#>   packages:
#>     tarshare
#>     stats
#>     graphics
#>     grDevices
#>     utils
#>     datasets
#>     methods
#>     base 
#>   library:
#>     NULL
tar_shared(
  simulations, stats::rnorm(2), cache,
  pattern = map(replicate_id), branch_context = list(replicate = replicate_id)
)
#> <tar_pattern> 
#>   name: simulations 
#>   description:  
#>   command:
#>     tarshare::shared_run(command = stats::rnorm(2), cache = list(
#>         path = "/tmp/Rtmp7EqBfI/shared-cache-1a89777bbce2", verify = TRUE, 
#>         timeout = Inf, visibility_timeout = 0, poll_interval = 0.05), 
#>         format = "rds", context = list(static = "6673d7954c1728d777660559e70bff8c99c0acb5879d3737a36c919570a005ce", 
#>             branch = list(replicate = replicate_id)), seed = 0L, 
#>         packages = c("tarshare", "stats", "graphics", "grDevices", 
#>         "utils", "datasets", "methods", "base"), owner = tarshare::shared_owner(store = targets::tar_path_store()), 
#>         localize = FALSE) 
#>   pattern:
#>     map(replicate_id) 
#>   format: rds 
#>   repository: local 
#>   iteration method: vector 
#>   error mode: stop 
#>   memory mode: auto 
#>   storage mode: worker 
#>   retrieval mode: auto 
#>   deployment mode: worker 
#>   priority: 0 
#>   resources:
#>     list() 
#>   cue:
#>     seed: TRUE
#>     file: TRUE
#>     iteration: TRUE
#>     repository: TRUE
#>     format: TRUE
#>     depend: TRUE
#>     command: TRUE
#>     mode: thorough 
#>   packages:
#>     tarshare
#>     stats
#>     graphics
#>     grDevices
#>     utils
#>     datasets
#>     methods
#>     base 
#>   library:
#>     NULL
tar_shared_raw("result", quote(sum(data)), cache)
#> <tar_stem> 
#>   name: result 
#>   description:  
#>   command:
#>     tarshare::shared_run(command = sum(data), cache = list(
#>         path = "/tmp/Rtmp7EqBfI/shared-cache-1a89777bbce2", verify = TRUE, 
#>         timeout = Inf, visibility_timeout = 0, poll_interval = 0.05), 
#>         format = "rds", context = list(static = "6673d7954c1728d777660559e70bff8c99c0acb5879d3737a36c919570a005ce", 
#>             branch = list()), seed = 0L, packages = c("tarshare", 
#>         "stats", "graphics", "grDevices", "utils", "datasets", "methods", 
#>         "base"), owner = tarshare::shared_owner(store = targets::tar_path_store()), 
#>         localize = FALSE) 
#>   format: rds 
#>   repository: local 
#>   iteration method: vector 
#>   error mode: stop 
#>   memory mode: auto 
#>   storage mode: worker 
#>   retrieval mode: auto 
#>   deployment mode: worker 
#>   priority: 0 
#>   resources:
#>     list() 
#>   cue:
#>     seed: TRUE
#>     file: TRUE
#>     iteration: TRUE
#>     repository: TRUE
#>     format: TRUE
#>     depend: TRUE
#>     command: TRUE
#>     mode: thorough 
#>   packages:
#>     tarshare
#>     stats
#>     graphics
#>     grDevices
#>     utils
#>     datasets
#>     methods
#>     base 
#>   library:
#>     NULL