track (version 1.0-13)

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=FAL

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

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 contains an experimental feature that allows users to supply their own plugin functions that specify cache rules. Currently, the plugin function can specify whether or not an object will be flushed from memory at the end of a top-level command. See track.plugins for further info.

Details

Valid option names and values are as follows: [object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object] 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: [object Object],[object Object],[object Object] 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='tltPurge')).

See Also

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

Examples

library(track)
unlink("tmp1", recursive=TRUE)
track.start("tmp1")
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("tmp1")
# 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("tmp1")
# now options previously changed are remembered (because track.options(..., save=TRUE) was used)
track.options(c("cache", "writeToDisk"))
track.stop(pos=1)