track (version 1.0-13)

track.setup: Setup and stop tracking

Description

Functions to setup and stop tracking, and resync to a changed disk db

Usage

track.start(dir="rdatadir", pos = 1, envir = as.environment(pos),
        create = TRUE,
        clobber = c("no", "files", "variables", "vars", "var"),
        discardMissing = FALSE,
        cache = NULL, cachePolicy = NULL, options = NULL,
        RDataSuffix = NULL, auto = NULL, readonly = FALSE,
        lockEnv = FALSE, check.Last = TRUE, verbose = TRUE)
track.stop(pos = 1, envir = as.environment(pos), all = FALSE,
        stop.on.error = FALSE, keepVars = FALSE, sessionEnd = FALSE,
        verbose = TRUE, detach = TRUE, callFrom = NULL)
track.rescan(pos = 1, envir = as.environment(pos), discardMissing = FALSE,
             forgetModified = FALSE, level = c("high", "low"), dryRun = FALSE)
track.Last()

Arguments

dir

The directory where tracking data is stored

pos

The search path position of the environment being tracked (default is 1 for the global environment)

envir

The environment being tracked. This is an alternate way (to the use of pos=) of specifying the environment being tracked, but should be rarely needed.

create

If TRUE, create the tracking directory if it doesn't exist

clobber

Controls action taken when there are objects of the same name in the tracking directory and in envir: no means stop; files means use the version from the tracking directory; and variables,

discardMissing

Discard all information about objects whose save file is missing?

cache

Should objects be keep cached in memory? Default is TRUE. This option is a shorthand way of supplying options=list(cache=...).

cachePolicy

Policy for keeping cached objects in memory. Default is tltPurge, for which cached objects are removed from memory at the end of a top-level task. This option is a shorthand way of supplying options=list(cachePolicy=...).

options

Option values (as a list) to be used for this tracking database. See track.options().

all

If TRUE, all tracked environment are unlinked

auto

If TRUE, automatically track new variables and deleted variables in the environment (through use of a task callback). If auto==NULL, take the value from getOptions("global.track.options")$autoTrack, and if

readonly

Logical flag indicating whether the tracking db should be attached in a readonly mode. The global environment (pos=1 in the search path) cannot be tracked in a readonly mode.

stop.on.error

If FALSE, failures to unlink a tracking environment are ignored, though a warning message is printed

keepVars

If FALSE, all tracked variables are removed and will be no longer accessible. If TRUE, tracked variables will be left as ordinary variables in the environment, as well as remaining in files.

detach

If TRUE, the environment attached to the search path (in a position other than 2) will be detached after stopping tracking, IF it was created by track.attach() and if there are no variables left remaining in the environm

callFrom

A character string used in a message saying where track.stop() was called from.

forgetModified

If TRUE, discard the versions of objects that are modified and in memory

RDataSuffix

The suffix to use for RData files. This should not normally need to be specified.

lockEnv

Should the environment be locked for a readonly tracking environment? The default is FALSE because locking the environment is irreversible, and it prevents rescanning or caching (because can't delete or add bindings)

check.Last

By default, a warning is issued if the .Last function in the track package is masked by any other .Last function. Supplying check.Last=FALSE inhibits this check and warning.

level

Should the rescan be done at a high or low level: a high level just stops tracking and restarts it; a low level tries to individually bring the environment in line with the file database.

dryRun

If TRUE, no changes are actualy made, but messages are printed describing what changes would be made.

sessionEnd

If TRUE, this is a call at the end of a session and no recovery from errors is possible -- just try to as best as can to save objects as appropriate.

verbose

print a message about what directory is being tracked?

Value

• track.start, track.stop, track.rescan:
  all return invisible(NULL) (this may change if it becomes clear what useful return values would be)
• track.Last:
  calls track.stop(all=TRUE) to ensure that all tracking information and objects are written to files, and removes tracked variables from the environment.

Simple Usage

These functions have many arguments providing much control over tracking, but the arguments used in simple usage are: track.start() track.start(dir = "rdatadir") track.stop(pos = 1, all = FALSE) track.rescan(pos = 2)

Details

[object Object],[object Object],[object Object],[object Object]

See Also

Overview and design of the track package.

Examples

library(track)
unlink("tmp1", recursive=TRUE)
track.start("tmp1")
x <- 33
X <- array(1:24, dim=2:4)
Y <- list(a=1:3,b=2)
X[2] <- -1
track.datadir(relative=TRUE)
track.filename(list=c("x", "X"))
track.summary(time=0, access=1, size=FALSE)
env.is.tracked(pos=1)
env.is.tracked(pos=2)
ls(all=TRUE)
track.stop(pos=1)
ls(all=TRUE)
track.start("tmp1")
ls(all=TRUE)
track.summary(time=0, access=1, size=FALSE)
track.stop(pos=1)
unlink("tmp1", recursive=TRUE)