mirror of
https://github.com/rstudio/shiny.git
synced 2026-02-08 05:35:07 -05:00
199 lines
8.3 KiB
R
199 lines
8.3 KiB
R
% Generated by roxygen2: do not edit by hand
|
|
% Please edit documentation in R/cache-disk.R
|
|
\name{diskCache}
|
|
\alias{diskCache}
|
|
\title{Create a disk cache object}
|
|
\usage{
|
|
diskCache(dir = NULL, max_size = 10 * 1024^2, max_age = Inf,
|
|
max_n = Inf, evict = c("lru", "fifo"), destroy_on_finalize = NULL,
|
|
missing = key_missing())
|
|
}
|
|
\arguments{
|
|
\item{dir}{Directory to store files for the cache. If \code{NULL} (the
|
|
default) it will create and use a temporary directory.}
|
|
|
|
\item{max_size}{Maximum size of the cache, in bytes. If the cache exceeds
|
|
this size, cached objects will be removed according to the value of the
|
|
\code{evict}.}
|
|
|
|
\item{max_age}{Maximum age of files in cache before they are evicted, in
|
|
seconds.}
|
|
|
|
\item{max_n}{Maximum number of objects in the cache. If the number of objects
|
|
exceeds this value, then cached objects will be removed according to the
|
|
value of \code{evict}.}
|
|
|
|
\item{evict}{The eviction policy to use to decide which objects are removed
|
|
when a cache pruning occurs. Currently, \code{"lru"} and \code{"fifo"} are
|
|
supported.}
|
|
|
|
\item{destroy_on_finalize}{If \code{TRUE}, then when the DiskCache object is
|
|
garbage collected, the cache directory and all objects inside of it will be
|
|
deleted from disk. If \code{FALSE}, it will do nothing when finalized. If
|
|
\code{NULL} (the default), then the behavior depends on the value of
|
|
\code{dir}: If \code{destroy_on_finalize=NULL} and \code{dir=NULL}, then a
|
|
temporary directory will be created and used for the cache, and it will be
|
|
deleted when the DiskCache is finalized. If
|
|
\code{destroy_on_finalize=NULL} and \code{dir} is \emph{not} \code{NULL},
|
|
then the directory will not be deleted when the DiskCache is finalized. In
|
|
short, when \code{destroy_on_finalize=NULL}, if the cache directory is
|
|
automatically created, it will be automatically deleted, and if the cache
|
|
directory is not automatically created, it will not be automatically
|
|
deleted.}
|
|
|
|
\item{missing}{A value to return, or a quoted expression to evaluate when
|
|
\code{get()} is called but the key is not present in the cache. The default
|
|
is a \code{\link{key_missing}} object. See section Missing keys for more
|
|
information.}
|
|
}
|
|
\description{
|
|
A disk cache object is a key-value store that saves the values as files in a
|
|
directory on disk. Objects can be stored and retrieved using the \code{get()}
|
|
and \code{set()} methods. Objects are automatically pruned from the cache
|
|
according to the parameters \code{max_size}, \code{max_age}, \code{max_n},
|
|
and \code{evict}.
|
|
}
|
|
\section{Missing keys}{
|
|
|
|
|
|
The \code{missing} parameter controls what happens when \code{get()} is
|
|
called with a key that is not in the cache (a cache miss). The default
|
|
behavior is to return a \code{\link{key_missing}} object. This is a
|
|
\emph{sentinel value} representing a missing key. You can test if the
|
|
returned value represents a missing key by using the
|
|
\code{\link{is.key_missing}} function. You can also have \code{get()}
|
|
return a different sentinel value, like \code{NULL}, or even throw an error
|
|
on a cache miss.
|
|
|
|
When the cache is created, you can supply a value for \code{missing}, which
|
|
sets the default value to be returned for missing values. It can also be
|
|
overridden when \code{get()} is called, by supplying a \code{missing}
|
|
argument, as in \code{cache$get("mykey", missing = NULL)}.
|
|
|
|
If your cache is configured so that \code{get()} returns a sentinel value
|
|
to represent a cache miss, then \code{set} will also not allow you to store
|
|
the sentinel value in the cache. It will throw an error if you attempt to
|
|
do so.
|
|
|
|
If \code{missing} is a quoted expression, then that expression will be
|
|
evaluated each time \code{get()} encounters missing key. If the evaluation
|
|
of the expression does not throw an error, then \code{get()} will return
|
|
the resulting value. However, it is more common for the expression to throw
|
|
an error. If an error is thrown, then \code{get()} will not return a value.
|
|
For example, you could use \code{quote(stop("Missing key"))}. If you use
|
|
this, the code that calls \code{get()} should be wrapped with
|
|
\code{\link{tryCatch}()} to gracefully handle missing keys.
|
|
}
|
|
|
|
\section{Cache pruning}{
|
|
|
|
|
|
Cache pruning occurs each time \code{get()} and \code{set()} are called, or
|
|
it can be invoked manually by calling \code{prune()}.
|
|
|
|
If there are any objects that are older than \code{max_age}, they will be
|
|
removed when a pruning occurs.
|
|
|
|
The \code{max_size} and \code{max_n} parameters are applied to the cache as
|
|
a whole, in contrast to \code{max_age}, which is applied to each object
|
|
individually.
|
|
|
|
If the number of objects in the cache exceeds \code{max_n}, then objects
|
|
will be removed from the cache according to the eviction policy, which is
|
|
set with the \code{evict} parameter. Objects will be removed so that the
|
|
number of items is \code{max_n}.
|
|
|
|
If the size of the objects in the cache exceeds \code{max_size}, then
|
|
objects will be removed from the cache. Objects will be removed from the
|
|
cache so that the total size remains under \code{max_size}. Note that the
|
|
size is calculated using the size of the files, not the size of disk space
|
|
used by the files -- these two values can differ because of files are
|
|
stored in blocks on disk. For example, if the block size is 4096 bytes,
|
|
then a file that is one byte in size will take 4096 bytes on disk.
|
|
}
|
|
|
|
\section{Eviction policies}{
|
|
|
|
|
|
If \code{max_n} or \code{max_size} are used, then objects will be removed
|
|
from the cache according to an eviction policy. The available eviction
|
|
policies are:
|
|
|
|
\describe{
|
|
\item{\code{"lru"}}{
|
|
Least Recently Used. The least recently used objects will be removed.
|
|
This uses the filesystem's atime property. Some filesystems do not
|
|
support atime, or have a very low atime resolution. The DiskCache will
|
|
check for atime support, and if the filesystem does not support atime,
|
|
a warning will be issued and the "fifo" policy will be used instead.
|
|
}
|
|
\item{\code{"fifo"}}{
|
|
First-in-first-out. The oldest objects will be removed.
|
|
}
|
|
}
|
|
}
|
|
|
|
\section{Sharing among multiple processes}{
|
|
|
|
|
|
The directory for a DiskCache can be shared among multiple R processes. To
|
|
do this, each R process should have a DiskCache object that uses the same
|
|
directory. Each DiskCache will do pruning independently of the others, so if
|
|
they have different pruning parameters, then one DiskCache may remove cached
|
|
objects before another DiskCache would do so.
|
|
|
|
When multiple processes share a cache directory, there are some potential
|
|
race conditions. For example, if your code calls \code{exists(key)} to check
|
|
if an object is in the cache, and then call \code{get(key)}, the object may
|
|
be removed from the cache in between those two calls, and \code{get(key)}
|
|
will throw an error. Instead of calling the two functions, it is better to
|
|
simply call \code{get(key)}, and use \code{tryCatch()} to handle the error
|
|
that is thrown if the object is not in the cache. This effectively tests for
|
|
existence and gets the object in one operation.
|
|
|
|
It is also possible for one processes to prune objects at the same time that
|
|
another processes is trying to prune objects. If this happens, you may see
|
|
a warning from \code{file.remove()} failing to remove a file that has
|
|
already been deleted.
|
|
}
|
|
|
|
\section{Methods}{
|
|
|
|
|
|
A disk cache object has the following methods:
|
|
|
|
\describe{
|
|
\item{\code{get(key, missing)}}{
|
|
Returns the value associated with \code{key}. If the key is not in the
|
|
cache, then it returns the value specified by \code{missing}. The
|
|
default value for \code{missing} when the DiskCache object is created,
|
|
but it can be overridden when \code{get()} is called.
|
|
}
|
|
\item{\code{set(key, value)}}{
|
|
Stores the \code{key}-\code{value} pair in the cache.
|
|
}
|
|
\item{\code{exists(key)}}{
|
|
Returns \code{TRUE} if the cache contains the key, otherwise
|
|
\code{FALSE}.
|
|
}
|
|
\item{\code{size()}}{
|
|
Returns the number of items currently in the cache.
|
|
}
|
|
\item{\code{keys()}}{
|
|
Returns a character vector of all keys currently in the cache.
|
|
}
|
|
\item{\code{reset()}}{
|
|
Clears all objects from the cache.
|
|
}
|
|
\item{\code{destroy()}}{
|
|
Clears all objects in the cache, and removes the cache directory from
|
|
disk.
|
|
}
|
|
\item{\code{prune()}}{
|
|
Prunes the cache, using the parameters specified by \code{max_size},
|
|
\code{max_age}, \code{max_n}, and \code{evict}.
|
|
}
|
|
}
|
|
}
|
|
|