Cache an object to a package's user-cache pins board

Stores an object in pkg's user-cache pins board, i.e. caches it to the filesystem.

Usage

cache_obj(board, x, id, qs_preset = c("fast", "balanced", "high", "archive"))

Arguments

board: Package's user-cache pins board.
x: Object to be cached.
id: Pin name uniquely identifying x in the pkg's user-cache pins board. A character scalar which is safe to use in paths of common file systems. Necessary to retrieve x again using get_obj(). An already existing pin named id will be silently overwritten.
qs_preset: Serialization algorithm preset to use. See qs::qsave() (section Presets) for details.

Value

x, invisibly.

Details

Note that cache_obj() will always overwrite an already existing cached object of the same id. See hash_fn_call() for a convenient way to create an id that uniquely identifies a function call. Or just use with_cache() that internally relies on the former.

Note that reading in the cached result from the user-cache pins board (i.e. from the filesystem) might produce a noticeable delay depending on the size of the cached object. Therefore, it's only recommended to cache results that take a considerable amount of time to recompute. To avoid the overhead of re-reading a cached result when accessing it multiple times, you can always assign it to an R variable to benefit from direct storage in memory.

Examples

# if the fn below would be part of a real package, we could instead define `this_pkg` globally
# using `this_pkg <- utils::packageName()`; instead, we now cache to pkgpins's cache (which
# itself never uses the cache)
board <- pkgpins::board(pkg = "pkgpins")

# let's define a fn that returns R pkg sys deps from cache
pkg_sys_deps <- function(pkg,
                         use_cache = TRUE,
                         max_cache_age = "6h") {
  fetch <- TRUE

  if (use_cache) {
    pin_name <- pkgpins::hash_fn_call(from_fn = "pkg_sys_deps",
                                      pkg)
    result <- pkgpins::get_obj(board = board,
                               id = pin_name,
                               max_age = max_cache_age)
    fetch <- is.null(result)
  }
  
  if (fetch) {
    result <-
      jsonlite::fromJSON(txt = paste0("https://sysreqs.r-hub.io/pkg/", pkg),
                         simplifyVector = FALSE) |>
      purrr::list_flatten()
  }
 
  if (use_cache && fetch) {
    pkgpins::cache_obj(board = board,
                       x = result,
                       id = pin_name)
  }

  result
}

# now get the sys deps for git2r for the first time (populating the cache)
pkg_sys_deps("git2r")
#> $libgit2
#> $libgit2$sysreqs
#> [1] "/libgit2/i"
#> 
#> $libgit2$platforms
#> $libgit2$platforms$DEB
#> [1] "libgit2-dev"
#> 
#> $libgit2$platforms$RPM
#> [1] "libgit2-devel"
#> 
#> $libgit2$platforms$PKGBUILD
#> [1] "libgit2"
#> 
#> $libgit2$platforms$`OSX/brew`
#> [1] "libgit2"
#> 
#> 
#> 
#> $openssl
#> $openssl$sysreqs
#> [1] "OpenSSL"
#> 
#> $openssl$platforms
#> $openssl$platforms$DEB
#> [1] "libssl-dev"
#> 
#> $openssl$platforms$PKGBUILD
#> [1] "openssl"
#> 
#> $openssl$platforms$`OSX/brew`
#> [1] "openssl@1.1"
#> 
#> $openssl$platforms$RPM
#> [1] "openssl-devel"
#> 
#> 
#> 
#> $zlib
#> $zlib$sysreqs
#> [1] "/\\bzlib\\b/i"
#> 
#> $zlib$platforms
#> $zlib$platforms$DEB
#> [1] "zlib1g-dev"
#> 
#> $zlib$platforms$`OSX/brew`
#> [1] "zlib"
#> 
#> $zlib$platforms$PKGBUILD
#> [1] "zlib"
#> 
#> $zlib$platforms$RPM
#> [1] "zlib-devel"
#> 
#> 
#> 
#> $libssh2
#> $libssh2$sysreqs
#> [1] "/libssh2/i"
#> 
#> $libssh2$platforms
#> $libssh2$platforms$DEB
#> [1] "libssh2-1-dev"
#> 
#> $libssh2$platforms$RPM
#> [1] "libssh2-devel"
#> 
#> $libssh2$platforms$PKGBUILD
#> [1] "libssh2"
#> 
#> $libssh2$platforms$`OSX/brew`
#> [1] "libssh2"
#> 
#> 
#> 

if (FALSE) {
# for the `max_cache_age` (we've set a default of 6h), the cached result will be returned
# (as long as `use_cache = TRUE`):
bench::mark("with cache" = pkg_sys_deps("git2r"),
            "without cache" = pkg_sys_deps("git2r", use_cache = FALSE),
            iterations = 10,
            relative = TRUE)}

# purge cache from the above example
pkgpins::purge_cache(board = board)