run_cpp_step_prebuilt: Run a C++ step from a pre-compiled library (worker behind...

View source: R/run-step-cpp.R

run_cpp_step_prebuiltR Documentation

Run a C++ step from a pre-compiled library (worker behind tarpolyglot_map)

Description

Reloads a compiled C++ library produced by compile_cpp_lib() (writing the embedded shared library to a temporary file, then re-evaluating the embedded wrapper source so it binds fresh, valid closures against this process's copy – see compile_cpp_lib() for why that is necessary, unlike Rust's run_rs_step_prebuilt()), then evaluates the R post-script exactly as run_cpp_step() does, with the compiled functions and the named inputs in scope. This is the function each branch target built by tar_target_cpp(..., pattern = tarpolyglot_map(...)) calls; it is exported so the call resolves at run time, but package users should not call it directly.

Usage

run_cpp_step_prebuilt(
  lib,
  post_script = NULL,
  inputs = list(),
  output = "object",
  name = NULL
)

Arguments

lib

A tp_cpp_lib bundle from compile_cpp_lib() (supplied by the companion ⁠<name>_cpp_lib⁠ target).

post_script

Path to an R script evaluated after compilation. The compiled C++ functions and the named inputs are in scope; its last expression is the target value (object mode), or it returns a character vector of file paths (file mode). Required for object mode. Accepts a file path or an inline tar_code() carrier; see the "Script arguments" section below.

inputs

Named character vector (or list) mapping the name seen inside the step (in the R environment and, after the hand-off, in the foreign session) to the name of an upstream target, e.g. c(x = "prepared_x"). Each upstream target becomes a dependency of this target and is bound by that name in the step environment; under dynamic branching the per-branch slice is bound instead.

output

Output mode: "object" (default) returns a converted R object, "file" returns a character vector of file paths (and defaults format to "file").

name

Character string, the branch's target name. Supplied automatically by the constructor; used only to name this branch's log files when polyglot_controller() was given a polyglot_log() (NULL – the default – disables logging for a direct call). Note this is the branch name, not ⁠<name>_cpp_lib⁠ – reloading a pre-compiled library never itself produces output to log.

Details

No C++ toolchain is needed here: reloading does not compile anything. See tarpolyglot_map() for the overall design.

Value

The value of the post-script (object mode) or a character vector of normalised file paths (file mode).

Script arguments

A worker receives whatever the constructor already resolved, which is one of two things: a path to a file on disk, or an inline carrier built by tar_code() that holds the code in memory. Both are accepted, so a direct call may pass either.

tar_target_path() is deliberately not a third form at this level. It is a constructor-level convenience: tar_target_py() and the other constructors rewrite it while the pipeline's DAG is built, so that by the time a worker runs it has already become the ordinary file path held by the upstream target. Handing the result of tar_target_path() straight to a worker therefore does not resolve to a file. The three forms as written in ⁠_targets.R⁠, and which of them tracks your edits, are covered in vignette("scripts").

See Also

tarpolyglot_map(), compile_cpp_lib(), run_cpp_step()

Examples

# Reloading needs a library built by compile_cpp_lib(), which needs a C++
# compiler, so this is gated on TARPOLYGLOT_EXAMPLES=true.
if (identical(Sys.getenv("TARPOLYGLOT_EXAMPLES"), "true")) {
  targets::tar_dir({
    # Normally invoked by tar_target_cpp(pattern = tarpolyglot_map(...)).
    writeLines(
      c("#include <Rcpp.h>",
        "// [[Rcpp::export]]",
        "double square(double x) { return x * x; }"),
      "square.cpp"
    )
    writeLines("square(x)", "post.R")
    lib <- compile_cpp_lib(script = "square.cpp")
    run_cpp_step_prebuilt(lib = lib, inputs = list(x = 21), post_script = "post.R")
  })
}

tarpolyglot documentation built on Nov. 22, 2026, 5:07 p.m.