Process Data with Optional Parallel Execution and Progress Reporting

This function executes a provided expression with progress reporting and optional parallel processing using the future and progressr packages. It logs the start and end times of the process along with a runtime message and supports custom logging, progress handlers, and execution plans.

Usage

Processing(
  func = substitute(NULL),
  n = NULL,
  start.message = NULL,
  end.message = NULL,
  use.multisession = TRUE,
  n.workers = NULL,
  handler = NULL,
  restore.defaults = TRUE,
  silent = FALSE,
  log = list()
)

Arguments

func: An expression (or a quoted function call) to be evaluated. The default is substitute(NULL). It is evaluated in the parent frame.
n: Optional integer indicating the number of items to be processed, used solely for logging purposes.
start.message: Optional character string specifying a custom start message. If NULL, a default message is generated based on the processing type and, if provided, the number of items.
end.message: Optional character string specifying a custom end message. If NULL, a runtime message is generated showing the elapsed time.
use.multisession: Logical. If TRUE (default), parallel processing using multisession is employed; otherwise, processing is sequential.
n.workers: Optional integer for the number of workers to be used in multisession mode. If NULL, it defaults to the number of available cores minus one (with a minimum of one).
handler: The progress handler to be used by the progressr package. If NULL and silent is FALSE, it defaults to "txtprogressbar". When silent is TRUE, the handler is set to "void".
restore.defaults: Logical. If TRUE (default), the current future plan is saved and restored upon exit.
silent: Logical. If TRUE, progress output is suppressed. Default is FALSE.
log: A list to collect log messages. Default is an empty list.

Value

A list with the following components:

result: The output resulting from the evaluation of func.
log: A list of log messages including start and end timestamps along with associated messages.

Details

The function begins by determining whether to use multisession (parallel) or sequential processing. It then logs the start time using a helper function, LogCat, and sets up the future plan accordingly. If restore.defaults is TRUE, the original plan is restored after execution.

A progress handler is configured via the progressr package. The provided expression is evaluated with progress reporting enabled. Upon completion, the function computes the elapsed time (with millisecond precision) and logs an end message. Finally, it returns a list containing the result of the evaluated expression and the log of messages.

Examples

if (FALSE) { # \dontrun{
  # Example: Process data with a simple sleep expression using multisession processing
  result <- Processing(
    func = quote({
      Sys.sleep(2)  # simulate a time-consuming task
      "Task Completed"
    }),
    n = 100,
    use.multisession = TRUE
  )
  print(result$result)
  print(result$log)
} # }