% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cache-memory.R
\name{memoryCache}
\alias{memoryCache}
\title{Create a memory cache object}
\usage{
memoryCache(max_size = 10 * 1024^2, max_age = Inf, max_n = Inf,
  evict = c("lru", "fifo"), missing = key_missing())
}
\arguments{
\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{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 memory cache object is a key-value store that saves the values in an
environment. 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}.
}
\details{
In a \code{MemoryCache}, R objects are stored directly in the cache; they are
not \emph{not} serialized before being stored in the cache. This contrasts
with other cache types, like \code{\link{DiskCache}}, where objects are
serialized, and the serialized object is cached. This can result in some
differences of behavior. For example, as long as an object is stored in a
MemoryCache, it will not be garbage collected.
}
\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}. The size is
  calculated by calling \code{\link{object.size}} on an object. Note that if
  two keys are associated with the same object, the size calculation will
  count the object's size twice, even though there is only one copy in
  memory.
}

\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, 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}.
    }
  }
}