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
1 2 3
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.
The search path position of the environment being tracked (default is 1 for the global environment)
The environment being tracked. This is an alternate way
(to the use of
A named list of option values to set.
The hidden environment in which tracked objects are stored. It is not necessary to supply this in normal use.
A list of old options to use, can only be suppled
Valid option names and values are as follows:
".Last"): vector of objects
to always keep in memory.
".Last" is here to avoid
difficulties quitting R if the tracking DB becomes unavailable.
"ff"): vector of
classes whose objects are always kept in memory.
here by default because
"ff" objects generally occupy only
a small amount of memory, and flushing the object from memory
causes unnecessary finalization calls on the external pointers in
"ff" objects, which changes their behavior.
logical (default TRUE) if TRUE, always save the summary on any change to the summary. Summaries are not saved for databases attached in a readonly mode.
character vector. Variables
whose class is in this vector are not auto-tracked. The default
"RODBC", because variables of that class do not work
after being saved and reloaded.
character vector (default
c("^\.track", "^\.required")) variables
whose name matches any of these regular expressions are not
(default -1) auto track will wait at least this many seconds between doing a full sync at the end of a top level task. If equal to zero, do a full sync at the end of each top level task. If less than zero, don't do a full sync. Doing a full sync can be slow, so this is off by default.
logical (default TRUE): keep objects in memory?
A function that specifies which objects to keep
in memory at the end of a top-level-task. track.plugins for
further info. Can be
The higher-level policy to follow regarding keeping objects in memory. Currently has two possible values - one of them allows special action at the end of a top-level-task:
No special action at end of task, i.e., follow option
Purge objects from memory at the end of a top-level task
Also affects when changes to objects are written to disk - see option
vector of string specifying variables to be clobbered silently when attaching a tracking db
character or logical (default
save(). Possible values are
uses gzip by default (i.e., when
save() offers the best tradeoff of
filesize and compression and decompression times.
integer (default 0) if > 0, print some diagnostic debugging messages
logical (default TRUE) if TRUE, record time & number of changes and accesses
"rda") suffix to use for files
containing saved R objects
logical (default TRUE for
track.attach() and FALSE
track.start()) should any changes be allowed to the files?
Note that this option is a function of how a tracking database is
accessed – it is not a property of the database itself. A
particular tracking database can attached on one R session with
readonly=TRUE and at the same time be attached to another R
unconditionally protect a tracking database from modification, use file permissions.
logical (default TRUE) if TRUE, record counts and times for access ("get") operations on tracked variables
logical, or integer value 0,1,2,3,4; controls
what info about accesses is output by
logical, or integer value 0,1,2,3 (see
track.summary() for the effect of these settings)
logical (default TRUE): always write changed
objects to disk? If
TRUE, when objects are written to disk depends on
cachePolicy="none": write objects immediately on a change;
cachePolicy="eotPurge": write changed objects at the end of a top-level task
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
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:
writeToDisk=TRUE (the default): always write an object to disk when it is
changed, and keep a copy in memory, so that an object only needs
to be read once
cache=FALSE: always write an
object to disk when it is changed, and don't keep a copy in memory
– need to read from disk whenever the object is referred to
cache=TRUE: don't write the object to disk - just keep
a copy in memory after it is first accessed and only write it when
track.save() or its friends is called. This
combination less robust because changed variables can be lost if R crashes,
or the user quits R without remembering to call
track.stop(). This mode of operation is like the
g.data package, but with automatically keeping track of
which variables have been changed and need to be written to disk
(and the writing of changed variables with one call to
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.
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
The value returned is a list of option values. If options were
specified as arguments, the old values of those options are returned
only.preprocess=TRUE was supplied). If no options were
specified as arguments, the full list of current option values is returned.
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
Tony Plate <email@example.com>
design of the
track package. See
track.plugins for description of cache plugin functions
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39
############################################################## # 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)