Home

Awesome

clojure.core.cache

core.cache is a Clojure contrib library providing the following features:

The clojure.core.cache namespace contains the immutable caches themselves. The clojure.core.cache.wrapped namespace contains the same API operating on caches wrapped in atoms, which is the "normal" use in the wild (introduced in 0.8.0).

core.cache is based on an old library named Clache that has been thoroughly deprecated.

The core.cache API is hard to use correctly. That's why clojure.core.cache.wrapped/lookup-or-miss exists: it encapsulates all the best practices around using the API and wraps it in an atom from the get-go. Read this article about the core.cache API by Dan Sutton for why it is important to use the API correctly!

Releases and Dependency Information

This project follows the version scheme MAJOR.MINOR.COMMITS where MAJOR and MINOR provide some relative indication of the size of the change, but do not follow semantic versioning. In general, all changes endeavor to be non-breaking (by moving to new names rather than by breaking existing names). COMMITS is an ever-increasing counter of commits since the beginning of this repository.

Latest stable release: 1.1.234

CLI/deps.edn dependency information:

org.clojure/core.cache {:mvn/version "1.1.234"}

Leiningen dependency information:

[org.clojure/core.cache "1.1.234"]

Maven dependency information:

<dependency>
  <groupId>org.clojure</groupId>
  <artifactId>core.cache</artifactId>
  <version>1.1.234</version>
</dependency>

Example Usage

The clojure.core.cache namespace provides an API for immutable caches where it is expected that you would manage storage of these data structures.

The clojure.core.cache.wrapped namespace provides the same API but over immutable caches already wrapped in an atom, which is generally a more intuitive API for straightforward use cases. In particular, this namespace adds a lookup-or-miss function which encapsulates the has?/hit/miss logic for the underlying cache as well as edge cases such as lookup returning nil if a cache item expires on fetch (e.g., TTL), and guaranteeing the value computing function is only called at most once.

The expectation is that you use either clojure.core.cache or clojure.core.cache.wrapped and you do not try to mix them.

    (require '[clojure.core.cache :as cache])

    ;; C1 is an immutable cache:
    (def C1 (cache/fifo-cache-factory {:a 1, :b 2}))

    (def C1' (if (cache/has? C1 :c)
               (cache/hit C1 :c)
               (cache/miss C1 :c 42)))

    ;=> {:a 1, :b 2, :c 42}

    (cache/lookup C1' :c)

    ;=> 42

    (get C1' :c) ; cache/lookup is implemented as get

    ;=> 42

    ;; a shorthand for the above conditional...
    (def C1' (cache/through-cache C1 :c (constantly 42)))
    ;; ...which uses a value to compute the result from the key...
    (cache/through-cache C1 my-key (partial jdbc/get-by-id db-spec :storage))
    ;; ...so you could fetch values from a database if they're not in cache...

    (cache/evict C1 :b)

    ;=> {:a 1}

    ;; since the caches are immutable, you would normally wrap them in an atom
    (def C2 (atom (cache/fifo-cache-factory {:a 1, :b 2})))

    (swap! C2 cache/through-cache :d (constantly 13))

    ;=> {:a 1, :b 3, :d 13}

    (swap! C2 cache/evict :b)

    ;=> {:a 1, :d 13}

    (get @C2 :a)

    ;=> 1

    ;; or use the wrapped API instead:
    (require '[clojure.core.cache.wrapped :as w])

    ;; in this case C3 is an atom containing a cache:
    (def C3 (w/fifo-cache-factory {:a 1, :b 2}))

    ;; operations modify the atom and return the updated cache:
    (w/through-cache C3 :d (constantly 13))

    ;=> {:a 1, :b 3, :d 13}

    ;; modifies the atom and returns the updated cache:
    (w/evict C3 :b)

    ;=> {:a 1, :d 13}

    ;; for some caches this is a mutating operation (e.g., TTL):
    (w/lookup C3 :a) ; or (get @C3 :a)

    ;=> 1

    ;; unique to the wrapped API, this combines through-cache and lookup
    ;; to return the looked up value, possibly after calling the passed in
    ;; function with the key to populate the cache if the key wasn't present:
    (w/lookup-or-miss C3 :b (constantly 42))

    ;=> 42

    @C3

    ;=> {:a 1, :d 13, :b 42}

    ;; calls (jdbc/get-by-id :storage my-key) in the event of a cache miss:
    (w/lookup-or-miss C3 my-key (partial jdbc/get-by-id db-spec :storage))

Refer to docstrings in the clojure.core.cache or clojure.core.cache.wrapped namespaces, or the autogenerated API documentation for additional documentation.

Developer Information

Change Log

Copyright and License

Copyright (c) Rich Hickey, Michael Fogus and contributors, 2012-2023. All rights reserved. The use and distribution terms for this software are covered by the Eclipse Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php) which can be found in the file epl-v10.html at the root of this distribution. By using this software in any fashion, you are agreeing to be bound bythe terms of this license. You must not remove this notice, or any other, from this software.