Turn the cache on or off

Turns on or off the saving and reuse of results on disk (the cache; see cacs_cache_dir()) by cacs_isochrone(), cacs_acs_prefetch(), and cacs_intersect_weight(), and so by cacs_run(). Turning the cache off does not delete saved results.

Usage

cacs_set_cache(
  enabled = TRUE,
  scope = c("session", "global"),
  confirm = interactive()
)

Arguments

enabled

A logical value: TRUE (the default) turns the cache on and FALSE turns it off. NA or any other value gives an error.

scope

A string: "session" (the default) sets the option for the current R session, and "global" also shows the line to add to the R startup file for later sessions (see Details).

confirm

Not used. It is kept so that code written for earlier versions still runs.

Value

TRUE, invisibly.

Details

cacs_set_cache() sets the option catchmentACS.cache_enabled for the rest of the R session and changes no file. With scope = "global", it also shows a line to add to the R startup file (see Startup) so that later sessions start with the same setting. For enabled = FALSE, the line sets this option. For enabled = TRUE, the line sets a cache folder that lasts between sessions instead, because the cache is on by default and its default folder is deleted when the session ends.

If an environment variable decides whether the cache is on (see the next section), the message says so.

Versions 0.3.0 to 0.5.1 wrote the setting to the startup file themselves, between the lines # catchmentACS v0.3 cache control and # end catchmentACS v0.3 cache control. R still runs these lines when a session starts, so the setting in them still applies. The package no longer reads or removes them; delete them by hand if they are not wanted.

Environment variables and options

These environment variables and options are read at every call, so a change takes effect at once. The rules are checked in this order, so CACS_NO_CACHE and CACS_CACHE_ENABLED take precedence over cacs_set_cache():

1. If the environment variable CACS_NO_CACHE is "1", "true", "yes", or "on" (ignoring case), the cache is off.

2. If the environment variable CACS_CACHE_ENABLED is set and not empty, the cache is on when its value is one of those four and off otherwise.

3. If the option catchmentACS.cache_enabled is TRUE or FALSE, it decides. Other values are ignored.

4. Otherwise, the cache is on (the default).

When the cache is on, one kind of saved result can be turned off on its own. The option catchmentACS.cache_isochrone, catchmentACS.cache_acs, or catchmentACS.cache_intersect set to FALSE turns off the cache of cacs_isochrone(), cacs_acs_prefetch(), or cacs_intersect_weight(). The environment variables CACS_CACHE_ISOCHRONE, CACS_CACHE_ACS, and CACS_CACHE_INTERSECT do the same when set to a value other than the four above, unless the matching option is TRUE.

See also

Other cache and configuration: cacs_cache_dir(), cacs_cache_status(), cacs_clear_cache(), cacs_get_cache_state()

Examples

# Turn the cache off for this session, check the setting, and restore it
old <- options("catchmentACS.cache_enabled")
cacs_set_cache(FALSE)
cacs_get_cache_state()$enabled
#> [1] FALSE

# Also show the line that keeps the cache off in later sessions;
# no file is changed
cacs_set_cache(FALSE, scope = "global")
#> The cache is off for this R session.
#> ℹ To keep it off in later sessions, add this line to the R startup file (see
#>   `?Startup`), and remove any other line there that sets
#>   `catchmentACS.cache_enabled`:
#>   options(catchmentACS.cache_enabled = FALSE)
options(old)