% 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"))
}
\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.}
}
\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{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)}}{
      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{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}.
    }
  }
}