% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cache.R
\name{diskCache}
\alias{diskCache}
\title{Create a disk cache object}
\usage{
diskCache(dir = tempfile("DiskCache-"), max_size = 5 * 1024^2,
  max_age = Inf, max_n = Inf, evict = "fifo",
  destroy_on_finalize = TRUE)
}
\arguments{
\item{dir}{Directory to store files for the cache. By default, it will 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.}
}
\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{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{Methods}{


 A disk cache object has the following methods:

  \describe{
    \item{\code{get(key)}}{
      Returns the value associated with \code{key}. If the key is not in the
      cache, this throws an error.
    }
    \item{\code{set(key, value)}}{
      Stores the \code{key}-\code{value} pair in the cache.
    }
    \item{\code{has(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}.
    }
  }
}