track (version 1.1.9)

track.sync: Synchronize the tracking database stored in files on disk to reflect changed, new, or deleted objects in R, and flush excess objects from memeory.

Description

Synchronize the tracking database to reflect new and/or deleted objects. This function is intended to be called by a task callback so that the tracking database automatically keeps up with new and deleted objects. The appropriate task callback is installed by track.start(..., auto = TRUE). If too much memory is occupied by objects, excess objects are flushed from memory.

This function differs from track.rescan() in that track.rescan() updates R view of the database to agree with changes on disk, while track.sync() is primarily intended to go the other way (to make the disk database agree with R).

Usage

track.sync(pos = 1, master=c("auto", "envir", "files"), envir = as.environment(pos), trackingEnv = getTrackingEnv(envir), full = TRUE, dryRun = FALSE, taskEnd = FALSE)

Arguments

pos

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

master

What to treat as the master for the synchronization. For a readonly tracked environment, the default auto will default to "files" (the only sensible interpretation). Otherwise, must be supplied (to avoid accidents with users mis-remembering the default.) When master="envir", changes are propagated from the R environment to the file system. When master="files", the R environment is made to reflect the file system (differences could result from changes to the R environment, or from changes to the file system, e.g., by another R process changing the database).

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.

trackingEnv

The environment that contains data for the tracking database.

full

If TRUE, do a full check, which involves checking that all apparently tracked variables do in fact have an active binding. If NA, only do a full check if more than track.options("autoTrackFullSyncWait") seconds have passed since the last full check (because this check can be slow when there are many variables in the environment.

dryRun

If TRUE, no changes are made to either the file system or to the R environment, but changes that would be made are printed out. Note that a change to a file for a tracked variable will not be detect.

taskEnd

Should be TRUE when called at the end of a top-level command task (i.e., when called by the task callback handler.)

Value

Returns an invisible list with the following components:

Details

Synchronizing the tracking database with the contents of the environment involves three tasks:

1. start tracking new untracked variables
2. for objects that have disappeared from the environment, delete them from the tracking database
3. check that all apparently tracked variables do in fact have an active binding

Currently, this function will not correctly handle the case where master="files" and where objects are cached and an underlying file is changed.

See Also

track.rescan for rescanning a tracked database after the files on disk have changed (this is usually only used for tracked environment attached at a position 2 or greater.)

Overview and design of the track package.