track (version 1.1.9)

track.options: Set and get tracking options on a tracked environment

Description

Set and get tracking options on a tracked environment. Each tracked environment has its own set of tracking options exists which can be changed indpendently. Global default values can be set in options("global.track.options").

Usage

track.options(..., pos = 1, envir = as.environment(pos), values=list(...), save = FALSE, clear=FALSE, delete=FALSE, trackingEnv, only.preprocess = FALSE, old.options = list())

Arguments

...

Either option names as character data, or specifications for setting options as named arguments or in a named list. See DETAILS for descriptions of options.

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.

values

A named list of option values to set. track.options(readonly=T) is equivalent to track.options(values=list(readonly=TRUE))

save

If TRUE, current options are saved to disk and will be used in future. Note that all current options settings are saved, not just the new settings made in this call.

clear

If TRUE, and the option can have multiple values (e.g., autoTrackExcludeClass), the current values are cleared prior to using the supplied values. The default behavior, with clear=FALSE and delete=FALSE is to add supplied values to multi-valued options, and to replace the value for single-valued options.

delete

If TRUE, and the option can have multiple values, the supplied values are removed from the current values (if they are not in the current values, they are silently ignored.)

trackingEnv

The hidden environment in which tracked objects are stored. It is not necessary to supply this in normal use.

only.preprocess

If TRUE, process any options specifications and return the full list of option settings with the values as specified, and defaults for all othe roptions. Stored options are neither accessed nor changed. Intended for internal use.

old.options

A list of old options to use, can only be suppled when only.preprocess=TRUE. Intended for internal use.

Value

The value returned is a list of option values. If options were specified as arguments, the old values of those options are returned (unless only.preprocess=TRUE was supplied). If no options were specified as arguments, the full list of current option values is returned.

Cache plugin functions

track allows users to supply their own plugin functions that specify cache rules. The plugin function is called at the end of a top-level command. The default plugin function implements a rule that flushes least-recently accessed large objects from the cache when more memory usage is over a threshold. See track.plugins for further info.

Details

Valid option names and values are as follows:

The option settings are saved as a list in an object called .trackingOptions in the tracking environment (with a copy mirrored to a file in the tracking dir if save=TRUE.)

The options can be used to tune performance to resource availability (time & memory) and robustness in the face of machine or user error. Some possible settings are:

The combination writeToDisk=FALSE and cache=FALSE is possible, but is unlikely to be desirable -- this will keep changed objects in memory, but will not keep merely fetched objects in memory.

The options maintainSummary, recordAccesses, and alwaysSaveSummary control when the object summary is updated and when it is saved to disk (the default is for it to be updated and saved to disk for every read and write access to an object, whether or not the object is cached in memory).

Global default values can be set in options("global.track.options") as a list like options(global.track.options=list(cache=TRUE, cachePolicy='eotPurge')).

See Also

Overview and design of the track package. See track.plugins for description of cache plugin functions

Examples

##############################################################
# Warning: running this example will cause variables currently
# in the R global environment to be written to .RData files
# in a tracking database on the filesystem under R's temporary
# directory, and will cause the variables to be removed temporarily
# from the R global environment.
# It is recommended to run this example with a fresh R session
# with no important variables in the global environment.
##############################################################

library(track)
track.start(dir=file.path(tempdir(), 'rdatadir6'))
x <- 33
X <- array(1:24, dim=2:4)
track.status()
track.options(cache=TRUE, writeToDisk=FALSE) # change for just this session
# different ways of retrieving option values
track.options(c("cache", "writeToDisk"))
track.options("cache", "writeToDisk")
track.options("cache")
track.options()
# see the effect of the changed options on the status of X (X is not saved to disk)
track.status()
X[1,1,1] <- 0
track.status()
track.flush()
track.status()
track.stop(pos=1)
track.start(dir=file.path(tempdir(), 'rdatadir6'))
# note that options previously changed are back at defaults (because default
# to track.options() is save=FALSE
track.options(c("cache", "writeToDisk"))
track.options(cache=TRUE, writeToDisk=FALSE, save=TRUE) # change the options on disk
track.options(c("cache", "writeToDisk"))
track.stop(pos=1)
track.start(dir=file.path(tempdir(), 'rdatadir6'))
# now options previously changed are remembered (because track.options(..., save=TRUE) was used)
track.options(c("cache", "writeToDisk"))
track.stop(pos=1, keepVars=TRUE)