immutant.cache documentation

Infinispan-backed implementations of core.cache and core.memoize
protocols supporting multiple replication options and more.



Functions for manipulating a shared, distributed cache.

Every 'put' function optionally accepts a map with the following
lifespan-oriented keys:

  :ttl - time-to-live, the max time the entry will live before expiry [-1]
  :idle - the time after which an entry will expire if not accessed [-1]
  :units - the units for the values of :ttl and :idle [:seconds]

Negative values imply no expiration.
Possible values for :units -- :days, :hours, :minutes, :seconds,
                              :milliseconds, :microseconds :nanoseconds

The conditional functions, e.g. put-if-*, are all atomic.


(delete cache key)(delete cache key value)
Delete the entry; value must match current if passed


(delete-all cache)
Clear all entries from the cache and return it


(put cache key value)(put cache key value options)
Put an entry in the cache


(put-all cache map)(put-all cache map options)
Put all the entries in cache


(put-if-absent cache key value)(put-if-absent cache key value options)
Put it in only if key is not already there


(put-if-present cache key value)(put-if-present cache key value options)
Put it in only if key is already there


(put-if-replace cache key old new)(put-if-replace cache key old new options)
Put it in only if key is there and current matches old


(create name & {:keys [seed], :as options})
Returns an object that implements both Mutable and
core.cache/CacheProtocol. A name is the only required argument. If
a cache by that name already exists, it will be restarted and all
its entries lost. Use lookup to obtain a reference to an existing
cache. The following options are supported:

The following options are supported [default]:
  :mode        Replication mode [:distributed or :local]
                 :local, :invalidated, :distributed, or :replicated
  :sync        Whether replication occurs synchronously [true]
  :persist     If non-nil, data persists across server restarts in a file
                 store; a string value names the directory [nil]
  :seed        A hash of initial entries [nil]
  :locking     Infinispan locking schemes [nil]
                 :optimisitic or :pessimistic
  :encoding    :edn :json or :none [:edn]
  :max-entries The maximum number of entries allowed in the cache [-1]
  :eviction    How entries are evicted when :max-entries is exceeded [:lirs]
                 :lru, :lirs, or :unordered
  :ttl         The max time the entry will live before expiry [-1]
  :idle        The time after which an entry will expire if not accessed [-1]
  :units       The units for the values of :ttl and :idle [:seconds]

The replication mode defaults to :distributed when clustered. When
not clustered, the value of :mode is ignored, and the cache will
be :local.

If :persist is true, cache entries will persist in the current
directory. Override this by setting :persist to a string naming the
desired directory.

A negative value for any numeric option means "unlimited".

The lifespan-oriented options (:ttl :idle :units) become the
default options for the functions of the Mutable protocol. But any
options passed to those functions take precedence over these.


(lookup name & {:as options})
Looks up a cache by name and returns it; returns nil if the cache doesn't exist.

All but the :encoding and lifespan-oriented create
options (:ttl :idle :units) are ignored if passed here.


(lookup-or-create name & opts)
A convenience method for creating a cache only if it doesn't
already exist. Takes the same options as create


(memo f name & options)
Memoize a function by associating its arguments with return values
stored in a possibly-clustered Infinispan-backed cache. Other than
the function to be memoized, arguments are the same as for the
create function.