R: Create a memory cache object

cache_mem {cachem} | R Documentation

## Create a memory cache object

### 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 `get()` and `set()` methods. Objects are automatically pruned from the cache according to the parameters `max_size`, `max_age`, `max_n`, and `evict`.

### Usage

    cache_mem(
      max_size = 512 * 1024^2,
      max_age = Inf,
      max_n = Inf,
      evict = c("lru", "fifo"),
      missing = key_missing(),
      logfile = NULL
    )

### Arguments

`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 `evict`. Use `Inf` for no size limit. The default is 1 gigabyte.
`max_age` | Maximum age of files in cache before they are evicted, in seconds. Use `Inf` for no age limit.
`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 `evict`. Use `Inf` for no limit of number of items.
`evict` | The eviction policy to use to decide which objects are removed when a cache pruning occurs. Currently, `"lru"` and `"fifo"` are supported.
`missing` | A value to return when `get(key)` is called but the key is not present in the cache. The default is a `key_missing()` object. It is actually an expression that is evaluated each time there is a cache miss. See section Missing keys for more information.
`logfile` | An optional filename or connection object to where logging information will be written. To log to the console, use `stderr()` or `stdout()`.

### Details

In a `cache_mem`, R objects are stored directly in the cache; they are not not serialized before being stored in the cache. This contrasts with other cache types, like `cache_disk()`, 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 cache_mem, it will not be garbage collected.

### Value

A memory caching object, with class `cache_mem`.

### Missing keys

The `missing` parameter controls what happens when `get()` is called with a key that is not in the cache (a cache miss). The default behavior is to return a `key_missing()` object. This is a sentinel value that indicates that the key was not present in the cache. You can test if the returned value represents a missing key by using the `is.key_missing()` function. You can also have `get()` return a different sentinel value, like `NULL`. If you want to throw an error on a cache miss, you can do so by providing an expression for `missing`, as in `missing = stop("Missing key")`.

When the cache is created, you can supply a value for `missing`, which sets the default value to be returned for missing values. It can also be overridden when `get()` is called, by supplying a `missing` argument. For example, if you use `cache$get("mykey", missing = NULL)`, it will return `NULL` if the key is not in the cache.

The `missing` parameter is actually an expression which is evaluated each time there is a cache miss. A quosure (from the rlang package) can be used.

If you use this, the code that calls `get()` should be wrapped with `tryCatch()` to gracefully handle missing keys.

@section Cache pruning:

Cache pruning occurs when `set()` is called, or it can be invoked manually by calling `prune()`.

When a pruning occurs, if there are any objects that are older than `max_age`, they will be removed.

The `max_size` and `max_n` parameters are applied to the cache as a whole, in contrast to `max_age`, which is applied to each object individually.

If the number of objects in the cache exceeds `max_n`, then objects will be removed from the cache according to the eviction policy, which is set with the `evict` parameter. Objects will be removed so that the number of items is `max_n`.

If the size of the objects in the cache exceeds `max_size`, then objects will be removed from the cache. Objects will be removed from the cache so that the total size remains under `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.

Another time that objects can be removed from the cache is when `get()` is called. If the target object is older than `max_age`, it will be removed and the cache will report it as a missing value.

### Eviction policies

If `max_n` or `max_size` are used, then objects will be removed from the cache according to an eviction policy. The available eviction policies are:

`"lru"`

  Least Recently Used. The least recently used objects will be removed.

`"fifo"`

  First-in-first-out. The oldest objects will be removed.

### Methods

A disk cache object has the following methods:

`get(key, missing)`

  Returns the value associated with `key`. If the key is not in the cache, then it evaluates the expression specified by `missing` and returns the value. If `missing` is specified here, then it will override the default that was set when the `cache_mem` object was created. See section Missing Keys for more information.

`set(key, value)`

  Stores the `key`-`value` pair in the cache.

`exists(key)`

  Returns `TRUE` if the cache contains the key, otherwise `FALSE`.

`size()`

  Returns the number of items currently in the cache.

`keys()`

  Returns a character vector of all keys currently in the cache.

`reset()`

  Clears all objects from the cache.

`destroy()`

  Clears all objects in the cache, and removes the cache directory from disk.

`prune()`

  Prunes the cache, using the parameters specified by `max_size`, `max_age`, `max_n`, and `evict`.

[Package cachem version 1.0.4 Index]