CacheProtocol

This is the protocol describing the basic cache capability.

Usage: (evict cache e)

Removes an entry from the cache

Usage: (has? cache e)

Checks if the cache contains a value associated with `e`

Usage: (hit cache e)

Is meant to be called if the cache is determined to contain a value
associated with `e`

Usage: (lookup cache e)
       (lookup cache e not-found)

Retrieve the value associated with `e` if it exists, else `nil` in
the 2-arg case.  Retrieve the value associated with `e` if it exists,
else `not-found` in the 3-arg case.

Usage: (miss cache e ret)

Is meant to be called if the cache is determined to **not** contain a
value associated with `e`

Usage: (seed cache base)

Is used to signal that the cache should be created with a seed.
The contract is that said cache should return an instance of its
own type.

BasicCache

FIFOCache

FnCache

LIRSCache

LRUCache

LUCache

SoftCache

TTLCacheQ

->BasicCache

Usage: (->BasicCache cache)

Positional factory function for class clojure.core.cache.BasicCache.

->FIFOCache

Usage: (->FIFOCache cache q limit)

Positional factory function for class clojure.core.cache.FIFOCache.

->FnCache

Usage: (->FnCache cache f)

Positional factory function for class clojure.core.cache.FnCache.

->LIRSCache

Usage: (->LIRSCache cache lruS lruQ tick limitS limitQ)

Positional factory function for class clojure.core.cache.LIRSCache.

->LRUCache

Usage: (->LRUCache cache lru tick limit)

Positional factory function for class clojure.core.cache.LRUCache.

->LUCache

Usage: (->LUCache cache lu limit)

Positional factory function for class clojure.core.cache.LUCache.

->SoftCache

Usage: (->SoftCache cache rcache rq)

Positional factory function for class clojure.core.cache.SoftCache.

->TTLCacheQ

Usage: (->TTLCacheQ cache ttl q gen ttl-ms)

Positional factory function for class clojure.core.cache.TTLCacheQ.

basic-cache-factory

Usage: (basic-cache-factory base)

Returns a pluggable basic cache initialized to `base`

fifo-cache-factory

Usage: (fifo-cache-factory base & {threshold :threshold, :or {threshold 32}})

Returns a FIFO cache with the cache and FIFO queue initialized to `base` --
the queue is filled as the values are pulled out of `base`.  If the associative
structure can guarantee ordering, then the said ordering will define the
eventual eviction order.  Otherwise, there are no guarantees for the eventual
eviction ordering.

This function takes an optional `:threshold` argument that defines the maximum number
of elements in the cache before the FIFO semantics apply (default is 32).

If the number of elements in `base` is greater than the limit then some items
in `base` will be dropped from the resulting cache.  If the associative
structure used as `base` can guarantee sorting, then the last `limit` elements
will be used as the cache seed values.  Otherwise, there are no guarantees about
the elements in the resulting cache.

lirs-cache-factory

Usage: (lirs-cache-factory base & {:keys [s-history-limit q-history-limit], :or {s-history-limit 32, q-history-limit 32}})

Returns an LIRS cache with the S & R LRU lists set to the indicated
limits.

lru-cache-factory

Usage: (lru-cache-factory base & {threshold :threshold, :or {threshold 32}})

Returns an LRU cache with the cache and usage-table initialized to `base` --
each entry is initialized with the same usage value.

This function takes an optional `:threshold` argument that defines the maximum number
of elements in the cache before the LRU semantics apply (default is 32).

lu-cache-factory

Usage: (lu-cache-factory base & {threshold :threshold, :or {threshold 32}})

Returns an LU cache with the cache and usage-table initialized to `base`.

This function takes an optional `:threshold` argument that defines the maximum number
of elements in the cache before the LU semantics apply (default is 32).

soft-cache-factory

Usage: (soft-cache-factory base)

Returns a SoftReference cache.  Cached values will be referred to with
SoftReferences, allowing the values to be garbage collected when there is
memory pressure on the JVM.

SoftCache is a mutable cache, since it is always based on a
ConcurrentHashMap.

through

Usage: (through cache item)
       (through value-fn cache item)
       (through wrap-fn value-fn cache item)

The basic hit/miss logic for the cache system.  Expects a wrap function and
value function.  The wrap function takes the value function and the item in question
and is expected to run the value function with the item whenever a cache
miss occurs.  The intent is to hide any cache-specific cells from leaking
into the cache logic itelf.

through-cache

Usage: (through-cache cache item)
       (through-cache cache item value-fn)
       (through-cache cache item wrap-fn value-fn)

The basic hit/miss logic for the cache system.  Like through but always has
the cache argument in the first position for easier use with swap! etc.

ttl-cache-factory

Usage: (ttl-cache-factory base & {ttl :ttl, :or {ttl 2000}})

Returns a TTL cache with the cache and expiration-table initialized to `base` --
each with the same time-to-live.

This function also allows an optional `:ttl` argument that defines the default
time in milliseconds that entries are allowed to reside in the cache.

basic-cache-factory

Usage: (basic-cache-factory base)

Returns a pluggable basic cache initialized to `base`

evict

Usage: (evict cache-atom e)

Removes an entry from the cache.

Returns the updated cache from the atom.

fifo-cache-factory

Usage: (fifo-cache-factory base & {threshold :threshold, :or {threshold 32}})

Returns a FIFO cache with the cache and FIFO queue initialized to `base` --
the queue is filled as the values are pulled out of `base`.  If the associative
structure can guarantee ordering, then the said ordering will define the
eventual eviction order.  Otherwise, there are no guarantees for the eventual
eviction ordering.

This function takes an optional `:threshold` argument that defines the maximum number
of elements in the cache before the FIFO semantics apply (default is 32).

If the number of elements in `base` is greater than the limit then some items
in `base` will be dropped from the resulting cache.  If the associative
structure used as `base` can guarantee sorting, then the last `limit` elements
will be used as the cache seed values.  Otherwise, there are no guarantees about
the elements in the resulting cache.

has?

Usage: (has? cache-atom e)

Checks if the cache contains a value associated with `e`.

Reads from the current version of the atom.

hit

Usage: (hit cache-atom e)

Is meant to be called if the cache is determined to contain a value
associated with `e`.

Returns the updated cache from the atom. Provided for completeness.

lirs-cache-factory

Usage: (lirs-cache-factory base & {:keys [s-history-limit q-history-limit], :or {s-history-limit 32, q-history-limit 32}})

Returns an LIRS cache with the S & R LRU lists set to the indicated
limits.

lookup

Usage: (lookup cache-atom e)
       (lookup cache-atom e not-found)

Retrieve the value associated with `e` if it exists, else `nil` in
the 2-arg case.  Retrieve the value associated with `e` if it exists,
else `not-found` in the 3-arg case.

Reads from the current version of the atom.

lookup-or-miss

Usage: (lookup-or-miss cache-atom e value-fn)
       (lookup-or-miss cache-atom e wrap-fn value-fn)

Retrieve the value associated with `e` if it exists, else compute the
value (using value-fn, and optionally wrap-fn), update the cache for `e`
and then perform the lookup again.

value-fn (and wrap-fn) will only be called (at most) once even in the
case of retries, so there is no risk of cache stampede.

Since lookup can cause invalidation in some caches (such as TTL), we
trap that case and retry (a maximum of ten times).

lru-cache-factory

Usage: (lru-cache-factory base & {threshold :threshold, :or {threshold 32}})

Returns an LRU cache with the cache and usage-table initialized to `base` --
each entry is initialized with the same usage value.

This function takes an optional `:threshold` argument that defines the maximum number
of elements in the cache before the LRU semantics apply (default is 32).

lu-cache-factory

Usage: (lu-cache-factory base & {threshold :threshold, :or {threshold 32}})

Returns an LU cache with the cache and usage-table initialized to `base`.

This function takes an optional `:threshold` argument that defines the maximum number
of elements in the cache before the LU semantics apply (default is 32).

miss

Usage: (miss cache-atom e ret)

Is meant to be called if the cache is determined to **not** contain a
value associated with `e`.

Returns the updated cache from the atom. Provided for completeness.

seed

Usage: (seed cache-atom base)

Is used to signal that the cache should be created with a seed.
The contract is that said cache should return an instance of its
own type.

Returns the updated cache from the atom. Provided for completeness.

size

Usage: (size cache-atom)

Obtain the approximate size/count of the wrapped cache.

The value returned is a point-in-time approximate count/size as the nature
of certain caches don't reflect their true size until a 'lookup-or-miss'
operation is invoked - such as the TTL cache.

Whilst it is an approximate value, the returned result can be useful for
metric tracking or decision making.

Returns an approximate count/size of the wrapped cache.

soft-cache-factory

Usage: (soft-cache-factory base)

Returns a SoftReference cache.  Cached values will be referred to with
SoftReferences, allowing the values to be garbage collected when there is
memory pressure on the JVM.

SoftCache is a mutable cache, since it is always based on a
ConcurrentHashMap.

through

Usage: (through cache-atom item)
       (through value-fn cache-atom item)
       (through wrap-fn value-fn cache-atom item)

The basic hit/miss logic for the cache system.  Expects a wrap function and
value function.  The wrap function takes the value function and the item in question
and is expected to run the value function with the item whenever a cache
miss occurs.  The intent is to hide any cache-specific cells from leaking
into the cache logic itelf.

through-cache

Usage: (through-cache cache-atom item)
       (through-cache cache-atom item value-fn)
       (through-cache cache-atom item wrap-fn value-fn)

The basic hit/miss logic for the cache system.  Like through but always has
the cache argument in the first position.

ttl-cache-factory

Usage: (ttl-cache-factory base & {ttl :ttl, :or {ttl 2000}})

Returns a TTL cache with the cache and expiration-table initialized to `base` --
each with the same time-to-live.

This function also allows an optional `:ttl` argument that defines the default
time in milliseconds that entries are allowed to reside in the cache.