Restart R programmatically — restartR • SpaDES.core

This will attempt to restart the R session, reloading all packages, and saving and reloading the simList. Currently, this is not intended for general use: it has many specialized pieces for using inside a spades call. The main purpose for doing this is to clear memory leaks (possibly deep in R https://github.com/r-lib/fastmap) that are not fully diagnosed. This is still very experimental. This should only be used if there are RAM limitations being hit with long running simulations. It has been tested to work Linux within Rstudio and at a terminal R session. The way to initiate restarting of R is simply setting the spades.restartRInterval or setting the equivalent parameter in the restartR core module via: simInit(..., params = list(.restartR = list(.restartRInterval = 1)), ...) greater than 0, which is the default, e.g., options("spades.restartRInterval" = 100). This is only intended to restart a simulation in exactly the same place as it was (i.e., cannot change machines), and because of the restart, the assignment of the spades call will be either to sim or the user must make such an assignment manually, e.g., sim <- savedSimEnv()$.sim, or perhaps, the safer sim <- Copy(savedSimEnv()$.sim). This is stated in a message.

restartR(
  sim,
  reloadPkgs = TRUE,
  .First = NULL,
  .RDataFile = getOption("spades.restartR.RDataFilename"),
  restartDir = getOption("spades.restartR.restartDir", NULL)
)

Arguments

sim: Required. A simList to be retained through the restart
reloadPkgs: Logical. If TRUE, it will attempt to reload all the packages as they were in previous session, in the same order. If FALSE, it will load no packages beyond normal R startup. Default TRUE
.First: A function to save to ~/.qs which will be loaded at restart from ~/.qs and run. Default is NULL, meaning it will use the non-exported SpaDES.core:::First. If a user wants to make a custom First file, it should built off that one.
.RDataFile: A filename for saving the simList. Defaults to getOption("spades.restartR.filename"), and the directory will be in restartDir. The simulation time will be mid-pended to this name, as in: basename(file), "_time", paddedFloatToChar(time(sim), padL = nchar(as.character(end(sim))))))
restartDir: A character string indicating root directory to save simList and other ancillary files during restart. Defaults to getOption("spades.restartR.restartDir", NULL). If NULL, then it will try, in order, outputPath(sim), modulePath(sim), inputPath(sim), cachePath(sim), taking the first one that is not inside the tempdir(), which will disappear during restart of R. The actual directory for a given spades call that is restarting will be: file.path(restartDir, "restartR", paste0(sim$._startClockTime, "_", .rndString)). The random string is to prevent parallel processes that started at the same clock time from colliding.

Value

invoked for side effect of restarting the R session

Details

The process responds to several options. Though under most cases, the default behaviour should suffice. These are of 3 types: restartRInterval the arguments to restartR and the arguments to saveSimList, these latter two using a dot to separate the function name and its argument. The defaults for two key options are: options("spades.restartR.restartDir" = NULL, meaning use file.path(restartDir, "restartR", paste0(sim$._startClockTime, "_", .rndString)) and options("spades.saveSimList.fileBackend" = 0), which means don't do anything with raster-backed files. See specific functions for defaults and argument meanings. The only difference from the default function values is with saveSimList argument fileBackend = FALSE during restartR by default, because it is assumed that the file backends will still be intact after a restart, so no need to move them all to memory.

Note

Because of the restarting, the object name of the original assignment of the spades call can not be preserved. The spades call will be assigned to sim in the .GlobalEnv.

Because this function is focused on restarting during a spades call, it will remove all objects in the .GlobalEnv, emulating q("no"). If the user wants to keep those objects, then they should be saved to disk immediately before the spades call. This can then be recovered immediately after the return from the spades call.

To keep the saved simList, use options("spades.restartR.clearFiles" = TRUE). The default is to treat these files as temporary files and so will be removed.