Description Usage Arguments Details Value Cache plugin functions Author(s) See Also Examples
View source: R/track.options.R
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")
.
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. |
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 |
values |
A named list of option values to set.
|
save |
If |
clear |
If |
delete |
If |
trackingEnv |
The hidden environment in which tracked objects are stored. It is not necessary to supply this in normal use. |
only.preprocess |
If |
old.options |
A list of old options to use, can only be suppled
when |
Valid option names and values are as follows:
character (default ".Last"
): vector of objects
to always keep in memory. ".Last"
is here to avoid
difficulties quitting R if the tracking DB becomes unavailable.
character (default "ff"
): vector of
classes whose objects are always kept in memory. "ff"
is
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
is "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
auto-tracked
(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 "none"
or NULL
.
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:
"none"
:No special action at end of task, i.e., follow option cache
"eotPurge"
:Purge objects from memory at the end of a top-level task
Also affects when changes to objects are written to disk - see option
writeToDisk
below.
vector of string specifying variables to be clobbered silently when attaching a tracking db
character or logical (default TRUE
)
passed to save()
. Possible values are "none"
,
"gzip"
, "xz"
, "bzip2"
. save()
currently
uses gzip by default (i.e., when compress=TRUE
), which
according to save()
offers the best tradeoff of
filesize and compression and decompression times.
numeric (default 1
)
passed to save()
integer (default 0) if > 0, print some diagnostic debugging messages
logical (default TRUE) if TRUE, record time & number of changes and accesses
character (default "rda"
) suffix to use for files
containing saved R objects
logical (default TRUE for track.attach()
and FALSE
for 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
session with readonly=FALSE
. To
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 track.summary()
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
:
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 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:
cache=TRUE
and
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
writeToDisk=TRUE
, 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
writeToDisk=FALSE
,
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.stop()
or
one of 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
track.save()
or track.stop()
).
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'))
.
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.
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.
Tony Plate <tplate@acm.org>
Overview and
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)
|
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.