├── .github ├── workflows │ ├── test.yml │ ├── snapshot.yml │ ├── doc-build.yml │ └── release.yml └── PULL_REQUEST_TEMPLATE ├── run-tests.sh ├── .gitignore ├── CONTRIBUTING.md ├── docs ├── Building.md ├── TTL.md ├── Including.md ├── LRU.md ├── FIFO.md ├── LU.md ├── release-notes │ ├── release-0.5.2.markdown │ ├── release-0.5.1.markdown │ ├── release-0.5.5.markdown │ ├── release-0.5.4.markdown │ └── release-0.5.6.markdown ├── README.md └── Using.md ├── deps.edn ├── pom.xml ├── src ├── test │ └── clojure │ │ └── clojure │ │ └── core │ │ ├── memoize │ │ ├── deprecation_test.clj │ │ └── regression_test.clj │ │ └── memoize_test.clj └── main │ └── clojure │ └── clojure │ └── core │ └── memoize.clj ├── README.md ├── LICENSE └── epl-v10.html /.github/workflows/test.yml: -------------------------------------------------------------------------------- 1 | name: Test 2 | 3 | on: [push] 4 | 5 | jobs: 6 | call-test: 7 | uses: clojure/build.ci/.github/workflows/test.yml@master 8 | -------------------------------------------------------------------------------- /run-tests.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | versions="1.9 1.10 1.11 1.12" 4 | for v in $versions 5 | do 6 | time clojure -M:test:$v 7 | if test $? != 0; then exit 1; fi 8 | done 9 | -------------------------------------------------------------------------------- /.github/workflows/snapshot.yml: -------------------------------------------------------------------------------- 1 | name: Snapshot on demand 2 | 3 | on: [workflow_dispatch] 4 | 5 | jobs: 6 | call-snapshot: 7 | uses: clojure/build.ci/.github/workflows/snapshot.yml@master 8 | secrets: inherit 9 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .classpath 2 | .clj-kondo/.cache 3 | .cpcache/ 4 | .idea 5 | .lein* 6 | .lsp/.cache 7 | .nrepl-port 8 | .portal/vs-code.edn 9 | .project 10 | .settings 11 | .vscode 12 | /build.boot 13 | lib 14 | multi-lib 15 | target 16 | .calva/repl.calva-repl 17 | -------------------------------------------------------------------------------- /.github/workflows/doc-build.yml: -------------------------------------------------------------------------------- 1 | name: Build API Docs 2 | 3 | on: 4 | workflow_dispatch: 5 | 6 | jobs: 7 | call-doc-build-workflow: 8 | uses: clojure/build.ci/.github/workflows/doc-build.yml@master 9 | with: 10 | project: clojure/core.memoize 11 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | This is a [Clojure contrib] project. 2 | 3 | Under the Clojure contrib [guidelines], this project cannot accept 4 | pull requests. All patches must be submitted via [JIRA]. 5 | 6 | See [Contributing] on the Clojure website for 7 | more information on how to contribute. 8 | 9 | [Clojure contrib]: https://clojure.org/community/contrib_libs 10 | [Contributing]: https://clojure.org/community/contributing 11 | [JIRA]: http://clojure.atlassian.net/browse/CMEMOIZE 12 | [guidelines]: https://clojure.org/community/contrib_howto 13 | -------------------------------------------------------------------------------- /.github/workflows/release.yml: -------------------------------------------------------------------------------- 1 | name: Release on demand 2 | 3 | on: 4 | workflow_dispatch: 5 | inputs: 6 | releaseVersion: 7 | description: "Version to release" 8 | required: true 9 | snapshotVersion: 10 | description: "Snapshot version after release" 11 | required: true 12 | 13 | jobs: 14 | call-release: 15 | uses: clojure/build.ci/.github/workflows/release.yml@master 16 | with: 17 | releaseVersion: ${{ github.event.inputs.releaseVersion }} 18 | snapshotVersion: ${{ github.event.inputs.snapshotVersion }} 19 | secrets: inherit -------------------------------------------------------------------------------- /.github/PULL_REQUEST_TEMPLATE: -------------------------------------------------------------------------------- 1 | Hi! Thanks for your interest in contributing to this project. 2 | 3 | Clojure contrib projects do not use GitHub issues or pull requests, and 4 | require a signed Contributor Agreement. If you would like to contribute, 5 | please read more about the CA and sign that first (this can be done online). 6 | 7 | Then go to this project's issue tracker in JIRA to create tickets, update 8 | tickets, or submit patches. For help in creating tickets and patches, 9 | please see: 10 | 11 | - Signing the CA: https://clojure.org/community/contributing 12 | - Creating Tickets: https://clojure.org/community/creating_tickets 13 | - Developing Patches: https://clojure.org/community/developing_patches 14 | - Contributing FAQ: https://clojure.org/community/contributing 15 | -------------------------------------------------------------------------------- /docs/Building.md: -------------------------------------------------------------------------------- 1 | Building core.memoize 2 | ===================== 3 | 4 | 1. Clone the [core.memoize git repository](http://github.com/clojure/core.memoize) or download its [source archive](https://github.com/clojure/core.memoize/zipball/master) 5 | 6 | 2. Run `mvn package` to generate a Jar file 7 | 8 | 3. Run `mvn install` to install the Jar into your local Maven repository 9 | 10 | To test that the build succeeded try: 11 | 12 | mvn clojure:repl 13 | 14 | This will launch a Clojure REPL. Try the following to exercise core.memoize: 15 | 16 | ```clojure 17 | (require '[clojure.core.memoize :as memo]) 18 | 19 | (def f (memo/memo #(do (Thread/sleep 5000) %))) 20 | 21 | (f 42) 22 | ;; wait 5 seconds 23 | ;;=> 42 24 | ``` 25 | 26 | Subsequent calls of the `f` function with the value `42` should return instantly. 27 | -------------------------------------------------------------------------------- /deps.edn: -------------------------------------------------------------------------------- 1 | ;; You can run clojure.core.memoize tests with: clj -A:test:runner 2 | ;; You can also specify an alias to select which version of Clojure to test 3 | ;; against: :1.9 :1.10 :1.11 :1.12 4 | 5 | {:paths ["src/main/clojure"] 6 | :deps {org.clojure/core.cache {:mvn/version "1.1.234"}} 7 | :aliases {:1.9 {:override-deps {org.clojure/clojure {:mvn/version "1.9.0"}}} 8 | :1.10 {:override-deps {org.clojure/clojure {:mvn/version "1.10.3"}}} 9 | :1.11 {:override-deps {org.clojure/clojure {:mvn/version "1.11.4"}}} 10 | :1.12 {:override-deps {org.clojure/clojure {:mvn/version "1.12.0"}}} 11 | :test 12 | {:extra-paths ["src/test/clojure"] 13 | :extra-deps {org.clojure/test.check {:mvn/version "1.1.1"} 14 | io.github.cognitect-labs/test-runner 15 | {:git/tag "v0.5.1" :git/sha "dfb30dd"}} 16 | :main-opts ["-m" "cognitect.test-runner" 17 | "-d" "src/test/clojure"]}}} 18 | -------------------------------------------------------------------------------- /docs/TTL.md: -------------------------------------------------------------------------------- 1 | # TTL memoization 2 | 3 | The time-to-live cache is one that evicts items that are older than a time-to-live threshold (in milliseconds). 4 | 5 | ## General use 6 | 7 | To create a core.memoize TTL-backed memoized function use the `clojure.core.memoize/ttl` function with an optional seed map or a `:ttl/threshold` parameter: 8 | 9 | (memo/ttl function <:ttl/threshold number>) 10 | 11 | Example code is as follows: 12 | 13 | ```clojure 14 | (ns your.lib 15 | (:require [clojure.core.memoize :as memo])) 16 | 17 | (def memoized-fun 18 | (memo/ttl identity {} :ttl/threshold 3)) 19 | ``` 20 | 21 | The default `:ttl/threshold` value is 2 seconds before the TTL logic is applied. 22 | 23 | Please read the [clojure.core.cache information regarding TTL caches](https://github.com/clojure/core.cache/wiki/TTL) for more detailed information, use cases and usage patterns. 24 | 25 | As always, you should measure your system's characteristics to determine the best eviction strategy for your purposes. 26 | -------------------------------------------------------------------------------- /docs/Including.md: -------------------------------------------------------------------------------- 1 | Including core.memoize in your projects 2 | ===================================== 3 | 4 | The core.memoize releases and snapshots are stored in the following repositories: 5 | 6 | * Release versions stored at [Maven Central](http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22org.clojure%22%20AND%20a%3A%22core.memoize%22) 7 | * Snapshot versions stored at [Sonatype](https://oss.sonatype.org/index.html#nexus-search;gav~org.clojure~core.memoize~~~) (url at ) 8 | 9 | ## Leiningen 10 | 11 | You can use core.memoize in your [Leiningen](https://github.com/technomancy/leiningen) projects with the following `:dependencies` directive in your `project.clj` file: 12 | 13 | [org.clojure/core.memoize "1.0.250"] 14 | 15 | ## Maven 16 | 17 | For Maven-driven projects, use the following slice of XML in your `pom.xml`'s `` section: 18 | 19 | 20 | org.clojure 21 | core.memoize 22 | 1.0.250 23 | 24 | 25 | Enjoy! 26 | -------------------------------------------------------------------------------- /docs/LRU.md: -------------------------------------------------------------------------------- 1 | # LRU memoization 2 | 3 | The least-recently-used memoization strategy is one that evicts items that are accessed least frequently once its threshold has been exceeded. 4 | 5 | > In simple terms, the LRU cache will remove the element in the cache that has not been accessed in the longest time. 6 | 7 | ## General use 8 | 9 | To create a core.memoize LRU-backed memoized function use the `clojure.core.memoize/lru` function with an optional seed map or a `:lru/threshold` parameter: 10 | 11 | (memo/lru function <:lru/threshold number>) 12 | 13 | Example code is as follows: 14 | 15 | ```clojure 16 | (ns your.lib 17 | (:require [clojure.core.memoize :as memo])) 18 | 19 | (def memoized-fun 20 | (memo/lru identity {} :lru/threshold 3)) 21 | ``` 22 | 23 | The default `:lru/threshold` value is 32 and refers to the number of elements in the cache required before the LRU logic is applied. 24 | 25 | Please read the [clojure.core.cache information regarding LRU caches](https://github.com/clojure/core.cache/wiki/LRU) for more detailed information, use cases and usage patterns. 26 | 27 | As always, you should measure your system's characteristics to determine the best eviction strategy for your purposes. 28 | -------------------------------------------------------------------------------- /docs/FIFO.md: -------------------------------------------------------------------------------- 1 | # FIFO memoization 2 | 3 | A First-In-First-Out memoization cache is one that uses queuing logic for its backing store, expunging the elements at the front of the queue when a predetermined threshold is exceeded. 4 | 5 | > In simple terms, the FIFO memoization cache will remove the element that has been in the cache the longest. 6 | 7 | ## General use 8 | 9 | To create a core.memoize FIFO-backed memoized function use the `clojure.core.memoize/fifo` function with an optional seed map or a `:fifo/threshold` parameter: 10 | 11 | (memo/fifo function <:fifo/threshold number>) 12 | 13 | Example code is as follows: 14 | 15 | ```clojure 16 | (ns your.lib 17 | (:require [clojure.core.memoize :as memo])) 18 | 19 | (def memoized-fun 20 | (memo/fifo identity {} :fifo/threshold 3)) 21 | ``` 22 | 23 | The default `:fifo/threshold` value is 32 and refers to the number of elements in the cache required before the FIFO logic is applied. 24 | 25 | Please read the [clojure.core.cache information regarding FIFO caches](https://github.com/clojure/core.cache/wiki/FIFO) for more detailed information, use cases and usage patterns. 26 | 27 | As always, you should measure your system's characteristics to determine the best eviction strategy for your purposes. 28 | -------------------------------------------------------------------------------- /docs/LU.md: -------------------------------------------------------------------------------- 1 | # LU memoization 2 | 3 | The least-used memoization strategy (sometimes called "Least Frequently Used") is a [variant of LRU](./LRU.md) that evicts items that are used least frequently once its threshold has been exceeded. 4 | 5 | > In simple terms, the LU cache will remove the element in the cache that has been accessed the least, regardless of time. 6 | 7 | ## General use 8 | 9 | To create a core.memoize LU-backed memoized function use the `clojure.core.memoize/lu` function with an optional seed map or a `:lu/threshold` parameter: 10 | 11 | (memo/lu function <:lu/threshold number>) 12 | 13 | Example code is as follows: 14 | 15 | ```clojure 16 | (ns your.lib 17 | (:require [clojure.core.memoize :as memo])) 18 | 19 | (def memoized-fun 20 | (memo/lu identity {} :lu/threshold 3)) 21 | ``` 22 | 23 | The default `:lu/threshold` value is 32 and refers to the number of elements in the cache required before the LU logic is applied. 24 | 25 | Please read the [clojure.core.cache information regarding LU caches](https://github.com/clojure/core.cache/wiki/LU) for more detailed information, use cases and usage patterns. 26 | 27 | As always, you should measure your system's characteristics to determine the best eviction strategy for your purposes. 28 | -------------------------------------------------------------------------------- /pom.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4.0.0 4 | core.memoize 5 | 1.1.267-SNAPSHOT 6 | core.memoize 7 | A memoization library for Clojure 8 | jar 9 | 10 | 11 | 12 | Eclipse Public License 1.0 13 | https://opensource.org/license/epl-1-0/ 14 | repo 15 | 16 | 17 | 18 | 19 | org.clojure 20 | pom.contrib 21 | 1.3.0 22 | 23 | 24 | 25 | 26 | fogus 27 | Fogus 28 | https://www.fogus.me 29 | 30 | 31 | 32 | 33 | 1.9.0 34 | 35 | 36 | 37 | 38 | org.clojure 39 | core.cache 40 | 1.1.234 41 | 42 | 43 | 44 | 45 | jira 46 | http://clojure.atlassian.net/browse/CMEMOIZE 47 | 48 | 49 | 50 | scm:git:git://github.com/clojure/core.memoize.git 51 | https://github.com/clojure/core.memoize 52 | HEAD 53 | 54 | 55 | 56 | 57 | sonatype-oss-snapshots 58 | https://oss.sonatype.org/content/repositories/snapshots 59 | 60 | 61 | 62 | -------------------------------------------------------------------------------- /docs/release-notes/release-0.5.2.markdown: -------------------------------------------------------------------------------- 1 | core.memoize v0.5.2 Release Notes 2 | ================================= 3 | 4 | core.memoize is a new Clojure contrib library providing the following features: 5 | 6 | * An underlying `PluggableMemoization` protocol that allows the use of customizable and swappable memoization caches that adhere to the synchronous `CacheProtocol` found in [core.cache](http://github.com/clojure/core.cache) 7 | 8 | * Memoization builders for implementations of common caching strategies, including: 9 | - First-in-first-out (`memo-fifo`) 10 | - Least-recently-used (`memo-lru`) 11 | - Least-used (`memo-lu`) 12 | - Time-to-live (`memo-ttl`) 13 | - Naive cache (`memo`) that duplicates the functionality of Clojure's `memoize` function 14 | 15 | * Functions for manipulating the memoization cache of `core.memoize` backed functions 16 | 17 | Places 18 | ------ 19 | 20 | * [Source code](https://github.com/clojure/core.memoize) 21 | * [Ticket system](http://clojure.atlassian.net/browse/CMEMOIZE) 22 | * [API Reference](https://clojure.github.io/core.memoize) 23 | 24 | Changes from v0.5.1 25 | ------------------- 26 | 27 | The v0.5.2 version of core.memoize is updated to work with the v0.6.1 version of [core.cache](http://github.com/clojure/core.cache/wiki) 28 | 29 | Plans 30 | ----- 31 | 32 | The following capabilities are under design, development, or consideration for future versions of core.memoize: 33 | 34 | * LIRS backed memoization 35 | * `SoftCache` backed memoization 36 | * Remove references to Unk 37 | * A [defn-memo](https://github.com/richhickey/clojure-contrib/blob/1c805bd0e515ea57028721ea54e6db4b0c791e20/src/main/clojure/clojure/contrib/def.clj#L143) macro 38 | * A [MapMaker](http://google-collections.googlecode.com/svn/trunk/javadoc/com/google/common/collect/MapMaker.html) style ctor interface 39 | * test.generative usage 40 | * More documentation and examples 41 | 42 | More planning is needed around capabilities not listed nor thought of. 43 | 44 | -------------------------------------------------------------------------------- /docs/release-notes/release-0.5.1.markdown: -------------------------------------------------------------------------------- 1 | core.memoize v0.5.1 Release Notes 2 | ================================= 3 | 4 | core.memoize is a new Clojure contrib library providing the following features: 5 | 6 | * An underlying `PluggableMemoization` protocol that allows the use of customizable and swappable memoization caches that adhere to the synchronous `CacheProtocol` found in [core.cache](http://github.com/clojure/core.cache) 7 | 8 | * Memoization builders for implementations of common caching strategies, including: 9 | - First-in-first-out (`memo-fifo`) 10 | - Least-recently-used (`memo-lru`) 11 | - Least-used (`memo-lu`) 12 | - Time-to-live (`memo-ttl`) 13 | - Naive cache (`memo`) that duplicates the functionality of Clojure's `memoize` function 14 | 15 | * Functions for manipulating the memoization cache of `core.memoize` backed functions 16 | 17 | core.memoize is based on a library named Unk, found at that is planned for deprecation. 18 | 19 | * [Source code](https://github.com/clojure/core.memoize) 20 | * [Ticket system](http://clojure.atlassian.net/browse/CMEMOIZE) 21 | 22 | Changes from Unk 23 | ------------------- 24 | 25 | The v0.5.1 version of core.memoize is based almost wholly on the final version of Unk, with the following changes: 26 | 27 | * All cache factory functions have been moved to core.cache 28 | * The `SoftCache` backed implementation was buggy and removed for now 29 | 30 | Plans 31 | ----- 32 | 33 | The following capabilities are under design, development, or consideration for future versions of core.memoize: 34 | 35 | * LIRS backed memoization 36 | * A [defn-memo](https://github.com/richhickey/clojure-contrib/blob/1c805bd0e515ea57028721ea54e6db4b0c791e20/src/main/clojure/clojure/contrib/def.clj#L143) macro 37 | * A [MapMaker](http://google-collections.googlecode.com/svn/trunk/javadoc/com/google/common/collect/MapMaker.html) style ctor interface 38 | * Reimplementation of a cache based on soft references 39 | * test.generative usage 40 | * Deprecation of Unk 41 | * Documentation and examples 42 | 43 | More planning is needed around capabilities not listed nor thought of. 44 | -------------------------------------------------------------------------------- /docs/README.md: -------------------------------------------------------------------------------- 1 | core.memoize 2 | ============ 3 | 4 | ## Table of Topics 5 | 6 | * Overview (this page) 7 | * [Including core.memoize in your projects](./Including.md) 8 | * [Example usages of core.memoize](./Using.md) 9 | * [Building core.memoize](./Building.md) 10 | 11 | ## The problem 12 | 13 | Value caching is sometimes needed. This need is often driven by the desire is to avoid calculating expensive operations such as inherently costly algorithms more often than necessary. The naive solution for this need is to perform some expensive operation once and cache the result. Therefore, whenever the same calculation is needed in the future it can be retrieved from cache more quickly than simply recalculating from scratch. 14 | 15 | Clojure provides a default way to cache the results of function calls using the `memoize` function: 16 | 17 | ```clojure 18 | (defn slow-calc [] 19 | (Thread/sleep 5000) 20 | 42) 21 | 22 | (def memo-calc (memoize slow-calc)) 23 | 24 | (memo-calc) 25 | ;; wait 5 seconds 26 | ;;=> 42 27 | 28 | (memo-calc) 29 | ;; instantly 30 | ;;=> 42 31 | ``` 32 | 33 | While appropriate for many problems, the naive caching provided by `memoize` can consume available memory as it never releases stored values. Therefore, the ideal situation is to expunge stored results that have expired, meant for single-use or less likely to be needed again. There are many general-purpose and domain-specific strategies for efficient cache population and eviction. The core.memoize library provides implementations of common caching strategies for use in memoization scenarios. 34 | 35 | ## Overview 36 | 37 | core.memoize is a Clojure contrib library providing the following features: 38 | 39 | * Implementations of some common memoization caching strategies, including: 40 | - [First-in-first-out](./FIFO.md) 41 | - [Least-recently-used](./LRU.md) 42 | - [Least-used](./LU.md) 43 | - [Time-to-live](./TTL.md) 44 | 45 | 46 | *The implementation of core.memoize is based on and heavily influenced by the excellent ['Memoize done right'](http://kotka.de/blog/2010/03/memoize_done_right.html) by Meikel Brandmeyer* and the [surrounding discussion with Christophe Grand and Eugen Dück](https://groups.google.com/forum/#!msg/clojure/NqE9FQ2DBoM/r3-q7FCHh_wJ).* 47 | 48 | ## Places 49 | 50 | * [Source code](https://github.com/clojure/core.memoize) 51 | * [Ticket system](http://clojure.atlassian.net/browse/CMEMOIZE) 52 | * [Examples and documentation](http://github.com/clojure/core.memoize/wiki) 53 | -------------------------------------------------------------------------------- /docs/release-notes/release-0.5.5.markdown: -------------------------------------------------------------------------------- 1 | core.memoize v0.5.5 Release Notes 2 | ================================= 3 | 4 | [core.memoize](https://github.com/clojure/core.memoize) is a Clojure contrib library providing the following features: 5 | 6 | * An underlying `PluggableMemoization` protocol that allows the use of customizable and swappable memoization caches that adhere to the synchronous `CacheProtocol` found in [core.cache](http://github.com/clojure/core.cache) 7 | 8 | * Memoization builders for implementations of common caching strategies, including: 9 | - First-in-first-out (`clojure.core.memoize/fifo`) 10 | - Least-recently-used (`clojure.core.memoize/lru`) 11 | - Least-used (`clojure.core.memoize/lu`) 12 | - Time-to-live (`clojure.core.memoize/ttl`) 13 | - Naive cache (`memo`) that duplicates the functionality of Clojure's `memoize` function 14 | 15 | * Functions for manipulating the memoization cache of `core.memoize` backed functions 16 | 17 | Usage 18 | ----- 19 | 20 | [Leiningen](https://github.com/technomancy/leiningen) dependency information: 21 | 22 | [org.clojure/core.memoize "0.5.5"] 23 | 24 | [Maven](http://maven.apache.org/) dependency information: 25 | 26 | 27 | org.clojure 28 | core.memoize 29 | 0.5.5 30 | 31 | 32 | Places 33 | ------ 34 | 35 | * [Source code](https://github.com/clojure/core.memoize) 36 | * [Ticket system](http://clojure.atlassian.net/browse/CMEMOIZE) 37 | * [API Reference](https://clojure.github.io/core.memoize) 38 | 39 | Changes from v0.5.4 40 | ------------------- 41 | 42 | The v0.5.5 version of core.memoize works with the v0.6.3 version of [core.cache](http://github.com/clojure/core.cache/wiki). In addition, the following bugs have been fixed: 43 | 44 | * Deprecated `memo-*` API 45 | * Added new API of form `(cache-type function <:cache-type/threshold int>)` 46 | 47 | Plans 48 | ----- 49 | 50 | The following capabilities are under design, development, or consideration for future versions of core.memoize: 51 | 52 | * LIRS backed memoization 53 | * `SoftCache` backed memoization 54 | * A [defn-memo](https://github.com/richhickey/clojure-contrib/blob/1c805bd0e515ea57028721ea54e6db4b0c791e20/src/main/clojure/clojure/contrib/def.clj#L143) macro 55 | * A [MapMaker](http://google-collections.googlecode.com/svn/trunk/javadoc/com/google/common/collect/MapMaker.html) style ctor interface 56 | * test.generative usage 57 | * More documentation and examples 58 | 59 | More planning is needed around capabilities not listed nor thought of. 60 | 61 | -------------------------------------------------------------------------------- /src/test/clojure/clojure/core/memoize/deprecation_test.clj: -------------------------------------------------------------------------------- 1 | ; Copyright (c) Rich Hickey and Michael Fogus. All rights reserved. 2 | ; The use and distribution terms for this software are covered by the 3 | ; Eclipse Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php) 4 | ; which can be found in the file epl-v10.html at the root of this distribution. 5 | ; By using this software in any fashion, you are agreeing to be bound by 6 | ; the terms of this license. 7 | ; You must not remove this notice, or any other, from this software. 8 | 9 | (ns ^{:doc "A memoization library for Clojure." 10 | :author "Michael Fogus"} 11 | clojure.core.memoize.deprecation-test 12 | (:use [clojure.test] 13 | [clojure.core.memoize] 14 | [clojure.core.cache :only [defcache lookup has? hit miss seed ttl-cache-factory]]) 15 | (:import (clojure.core.memoize PluggableMemoization) 16 | (clojure.core.cache CacheProtocol))) 17 | 18 | (def id (memo identity)) 19 | 20 | (deftest test-memo-fifo 21 | (let [mine (memo-fifo identity 2)] 22 | (testing "that when the limit threshold is not breached, the cache works like the basic version" 23 | (are [x y] = 24 | 42 (mine 42) 25 | {[42] 42} (snapshot mine) 26 | 43 (mine 43) 27 | {[42] 42, [43] 43} (snapshot mine) 28 | 42 (mine 42) 29 | {[42] 42, [43] 43} (snapshot mine))) 30 | (testing "that when the limit is breached, the oldest value is dropped" 31 | (are [x y] = 32 | 44 (mine 44) 33 | {[44] 44, [43] 43} (snapshot mine))))) 34 | 35 | (deftest test-memo-lru 36 | (let [mine (memo-lru identity)] 37 | (are [x y] = 38 | 42 (id 42) 39 | 43 (id 43) 40 | {[42] 42, [43] 43} (snapshot id) 41 | 44 (id 44) 42 | {[44] 44, [43] 43} (snapshot id) 43 | 43 (id 43) 44 | 0 (id 0) 45 | {[0] 0, [43] 43} (snapshot id)))) 46 | 47 | (deftest test-ttl 48 | (let [mine (memo-ttl identity 2000)] 49 | (are [x y] = 50 | 42 (id 42) 51 | {[42] 42} (snapshot id)) 52 | (Thread/sleep 3000) 53 | (are [x y] = 54 | 43 (id 43) 55 | {[43] 43} (snapshot id)))) 56 | 57 | (deftest test-memo-lu 58 | (let [mine (memo-lu identity 3)] 59 | (are [x y] = 60 | 42 (id 42) 61 | 42 (id 42) 62 | 43 (id 43) 63 | 44 (id 44) 64 | {[44] 44, [42] 42} (snapshot id)))) 65 | -------------------------------------------------------------------------------- /docs/release-notes/release-0.5.4.markdown: -------------------------------------------------------------------------------- 1 | core.memoize v0.5.4 Release Notes 2 | ================================= 3 | 4 | [core.memoize](https://github.com/clojure/core.memoize) is a Clojure contrib library providing the following features: 5 | 6 | * An underlying `PluggableMemoization` protocol that allows the use of customizable and swappable memoization caches that adhere to the synchronous `CacheProtocol` found in [core.cache](http://github.com/clojure/core.cache) 7 | 8 | * Memoization builders for implementations of common caching strategies, including: 9 | - First-in-first-out (`memo-fifo`) 10 | - Least-recently-used (`memo-lru`) 11 | - Least-used (`memo-lu`) 12 | - Time-to-live (`memo-ttl`) 13 | - Naive cache (`memo`) that duplicates the functionality of Clojure's `memoize` function 14 | 15 | * Functions for manipulating the memoization cache of `core.memoize` backed functions 16 | 17 | Usage 18 | ----- 19 | 20 | [Leiningen](https://github.com/technomancy/leiningen) dependency information: 21 | 22 | [org.clojure/core.memoize "0.5.4"] 23 | 24 | [Maven](http://maven.apache.org/) dependency information: 25 | 26 | 27 | org.clojure 28 | core.memoize 29 | 0.5.4 30 | 31 | 32 | Places 33 | ------ 34 | 35 | * [Source code](https://github.com/clojure/core.memoize) 36 | * [Ticket system](http://clojure.atlassian.net/browse/CMEMOIZE) 37 | * [API Reference](https://clojure.github.io/core.memoize) 38 | 39 | Changes from v0.5.3 40 | ------------------- 41 | 42 | The v0.5.4 version of core.memoize works with the v0.6.3 version of [core.cache](http://github.com/clojure/core.cache/wiki). In addition, the following bugs have been fixed: 43 | 44 | * [CMEMOIZE-5](http://clojure.atlassian.net/browse/CMEMOIZE-5): Changed to never assume that the value retrieved from the cache is non-nil. This was causing an occassional issue with TTL caches that timed out between checking for a value and retrieving it. 45 | * [CMEMOIZE-2](http://clojure.atlassian.net/browse/CMEMOIZE-2): All references to Unk have been removed. 46 | 47 | Plans 48 | ----- 49 | 50 | The following capabilities are under design, development, or consideration for future versions of core.memoize: 51 | 52 | * LIRS backed memoization 53 | * `SoftCache` backed memoization 54 | * A [defn-memo](https://github.com/richhickey/clojure-contrib/blob/1c805bd0e515ea57028721ea54e6db4b0c791e20/src/main/clojure/clojure/contrib/def.clj#L143) macro 55 | * A [MapMaker](http://google-collections.googlecode.com/svn/trunk/javadoc/com/google/common/collect/MapMaker.html) style ctor interface 56 | * test.generative usage 57 | * More documentation and examples 58 | 59 | More planning is needed around capabilities not listed nor thought of. 60 | 61 | -------------------------------------------------------------------------------- /docs/release-notes/release-0.5.6.markdown: -------------------------------------------------------------------------------- 1 | core.memoize v0.5.6 Release Notes 2 | ================================= 3 | 4 | [core.memoize](https://github.com/clojure/core.memoize) is a Clojure contrib library providing the following features: 5 | 6 | * An underlying `PluggableMemoization` protocol that allows the use of customizable and swappable memoization caches that adhere to the synchronous `CacheProtocol` found in [core.cache](http://github.com/clojure/core.cache) 7 | 8 | * Memoization builders for implementations of common caching strategies, including: 9 | - First-in-first-out (`clojure.core.memoize/fifo`) 10 | - Least-recently-used (`clojure.core.memoize/lru`) 11 | - Least-used (`clojure.core.memoize/lu`) 12 | - Time-to-live (`clojure.core.memoize/ttl`) 13 | - Naive cache (`memo`) that duplicates the functionality of Clojure's `memoize` function 14 | 15 | * Functions for manipulating the memoization cache of `core.memoize` backed functions 16 | 17 | Usage 18 | ----- 19 | 20 | [Leiningen](https://github.com/technomancy/leiningen) dependency information: 21 | 22 | [org.clojure/core.memoize "0.5.6"] 23 | 24 | [Maven](http://maven.apache.org/) dependency information: 25 | 26 | 27 | org.clojure 28 | core.memoize 29 | 0.5.6 30 | 31 | 32 | Places 33 | ------ 34 | 35 | * [Source code](https://github.com/clojure/core.memoize) 36 | * [Ticket system](http://clojure.atlassian.net/browse/CMEMOIZE) 37 | * [API Reference](https://clojure.github.io/core.memoize) 38 | 39 | Changes from v0.5.5 40 | ------------------- 41 | 42 | The v0.5.6 version of core.memoize works with the v0.6.3 version of [core.cache](http://github.com/clojure/core.cache/wiki). In addition, the following bugs have been fixed, or features added: 43 | 44 | * [CMEMOIZE-4](http://clojure.atlassian.net/browse/CMEMOIZE-4) - `memo-clear!` function now takes an optional args to limit evictions. 45 | 46 | * [CMEMOIZE-6](http://clojure.atlassian.net/browse/CMEMOIZE-6) - Widenes the contract on the types of callables allowed. 47 | 48 | * [CMEMOIZE-7](http://clojure.atlassian.net/browse/CMEMOIZE-7) - Fixed issues link in README. 49 | 50 | Plans 51 | ----- 52 | 53 | The following capabilities are under design, development, or consideration for future versions of core.memoize: 54 | 55 | * LIRS backed memoization 56 | * `SoftCache` backed memoization 57 | * A [defn-memo](https://github.com/richhickey/clojure-contrib/blob/1c805bd0e515ea57028721ea54e6db4b0c791e20/src/main/clojure/clojure/contrib/def.clj#L143) macro 58 | * A [MapMaker](http://google-collections.googlecode.com/svn/trunk/javadoc/com/google/common/collect/MapMaker.html) style ctor interface 59 | * test.generative usage 60 | * More documentation and examples 61 | 62 | More planning is needed around capabilities not listed nor thought of. 63 | 64 | -------------------------------------------------------------------------------- /src/test/clojure/clojure/core/memoize/regression_test.clj: -------------------------------------------------------------------------------- 1 | ; Copyright (c) Rich Hickey and Michael Fogus. All rights reserved. 2 | ; The use and distribution terms for this software are covered by the 3 | ; Eclipse Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php) 4 | ; which can be found in the file epl-v10.html at the root of this distribution. 5 | ; By using this software in any fashion, you are agreeing to be bound by 6 | ; the terms of this license. 7 | ; You must not remove this notice, or any other, from this software. 8 | 9 | (ns ^{:doc "A memoization library for Clojure." 10 | :author "Michael Fogus"} 11 | clojure.core.memoize.regression-test 12 | (:use [clojure.test] 13 | [clojure.core.memoize] 14 | [clojure.core.cache :only [defcache lookup has? hit miss seed ttl-cache-factory]]) 15 | (:import (clojure.core.memoize PluggableMemoization) 16 | (clojure.core.cache CacheProtocol))) 17 | 18 | (deftest test-regression-cmemoize-5 19 | (testing "that the TTL doesn't bomb on race-condition" 20 | (try 21 | (let [id (ttl identity :ttl/threshold 100)] 22 | (dotimes [_ 10000000] (id 1))) 23 | (is (= 1 1)) 24 | (catch NullPointerException npe 25 | (is (= 1 0)))))) 26 | 27 | (deftest test-regression-cmemoize-7 28 | (testing "that a memoized function that throws a RTE continues to retry" 29 | (let [doit (fn [] (throw (RuntimeException. "Foo"))) 30 | it (lru doit)] 31 | (is (= :RTE 32 | (try 33 | (it) 34 | (catch Exception _ 35 | (try 36 | (it) 37 | (catch NullPointerException _ 38 | :NPE) 39 | (catch RuntimeException _ 40 | :RTE) 41 | (catch Exception e 42 | (class e)))))))))) 43 | 44 | (defn- test-helper-26 45 | ([] 100) 46 | ([i] (inc i))) 47 | 48 | (deftest test-regression-cmemoize-26 49 | (let [mine (memo test-helper-26)] 50 | (testing "that memo-swap! is respected for zero arity" 51 | (is (= 100 (mine))) 52 | (is (= 201 (mine 200))) 53 | (is (= {[] 100, [200] 201} (snapshot mine))) 54 | (memo-swap! mine {[] :something [200] :else}) 55 | (is (= {[] :something, [200] :else} (snapshot mine))) 56 | ;; unary works... 57 | (is (= :else (mine 200))) 58 | ;; ...but 0-arity still has old value... 59 | (is (= :something (mine))) 60 | ;; ...and snapshot gets changed 61 | (is (= {[] :something, [200] :else} (snapshot mine)))))) 62 | 63 | (deftest test-regression-cmemoize-27 64 | (testing "that seed makes elements derefable" 65 | (let [mine (memo identity) 66 | mine (vary-meta mine update-in [:clojure.core.memoize/cache] 67 | swap! seed {[:a] :b [:b] :c})] 68 | (is (= :b (mine :a))) 69 | (is (= :c (mine :b))) 70 | (is (= :x (mine :x)))))) 71 | -------------------------------------------------------------------------------- /docs/Using.md: -------------------------------------------------------------------------------- 1 | # Using core.memoize 2 | 3 | *note: see the page on [including core.memoize](./Including.md) before you begin this section* 4 | 5 | ## Basic usage pattern 6 | 7 | To use the memoization cache implementations you first need to require the proper namespace: 8 | 9 | ```clojure 10 | (require '[clojure.core.memoize :as memo]) 11 | ``` 12 | 13 | Next you can create some function that you'd like to memoize. For illustrative purposes I'll create one that is intentionally slow: 14 | 15 | ```clojure 16 | (defn slowly [n] 17 | (Thread/sleep 5000) 18 | n) 19 | ``` 20 | 21 | I can then memoize this function using `core.memoize/memo` which is an augmented replacement for `clojure.core/memoize`: 22 | 23 | ```clojure 24 | (def once-slowly (memo/memo slowly)) 25 | 26 | (once-slowly 42) 27 | ;; wait 5 seconds 28 | ;;=> 42 29 | 30 | (once-slowly 42) 31 | ;; instantly 32 | ;;=> 42 33 | ``` 34 | 35 | One advantage of using the `clojure.core.memoize/memo` function over the one provided in Clojure is that the former allows you to evict certain entries as needed, shown next. 36 | 37 | ### Evicting cached entries 38 | 39 | To explicitly evict an element in a memoization cache, use the `clojure.core.memoize/memo-clear!` function: 40 | 41 | ```clojure 42 | (memo/memo-clear! once-slowly [42]) 43 | 44 | (once-slowly 42) 45 | ;; wait 5 seconds 46 | ;;=> 42 47 | ``` 48 | 49 | The argument to `clojure.core.memoize/memo-clear!` is a vector of the precise argument values that you'd like to clear. You can not pass the argument vector to instead clear the entire memoization cache for a function. 50 | 51 | ### Overriding the cache keys 52 | 53 | By default, the entire argument list is used as a key into the cached results. Sometimes you will want to cache a function where one or more of its arguments don't affect the results directly and you would rather ignore them from a cache key point of view. 54 | 55 | You can do that by specifying metadata on the function being cached, telling the memoization functions how to turn the arguments into a cache key: 56 | 57 | ```clojure 58 | (defn ^{:clojure.core.memoize/args-fn rest} 59 | fetch-user-from-db 60 | [db-spec user-id] 61 | ...) 62 | 63 | (def get-user (memo/ttl #'fetch-user-from-db)) 64 | ``` 65 | 66 | This tells memoization that the cache key for any given call is `(rest args)` so the `db-spec` argument will not be considered as part of the cache key. The supplied `args-fn` can perform any transformation from an argument list to a cache key but it is expected the most common use will be to remove one or more arguments from the cache key. 67 | 68 | Note: because you want memoization to read the metadata from your function, you must pass the Var in, rather than just the function name. 69 | 70 | ## Using a memoization cache strategy 71 | 72 | You could also use a memoization strategy that will expire its entries based on an expiration parameter, shown below: 73 | 74 | ```clojure 75 | (def sometimes-slowly (memo/ttl slowly :ttl/threshold 10000)) 76 | 77 | (sometimes-slowly 42) 78 | ;; wait 5 seconds 79 | ;;=> 42 80 | 81 | (sometimes-slowly 42) 82 | ;; instantly 83 | ;;=> 42 84 | ``` 85 | 86 | The `:ttl/threshold` flag states that entries in the memoization cache older than 10,000 milliseconds (10 seconds) should be evicted from the internal cache. If you wait some time after running the code above, you should see the function call slow down again: 87 | 88 | ```clojure 89 | (sometimes-slowly 42) 90 | ;; wait 5 seconds 91 | ;;=> 42 92 | ``` 93 | 94 | For specific information about eviction policies and thresholds, view the specific documentation for each cache type listed in the next section. 95 | 96 | ## Builtin cache implementations 97 | 98 | core.memoize comes with a number of builtin memoization cache implementations, including (*click through for specific information*): 99 | 100 | * [FIFO cache](./FIFO.md) 101 | * [LRU cache](./LRU.md) 102 | * [LU cache](./LU.md) 103 | * [TTL cache](./TTL.md) 104 | 105 | Enjoy. 106 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | clojure.core.memoize 2 | ======================================== 3 | 4 | [core.memoize](https://github.com/clojure/core.memoize) is a Clojure contrib library providing the following features: 5 | 6 | * An underlying `PluggableMemoization` protocol that allows the use of customizable and swappable memoization caches that adhere to the synchronous `CacheProtocol` found in [core.cache](https://github.com/clojure/core.cache) 7 | 8 | * Memoization builders for implementations of common caching strategies, including: 9 | - First-in-first-out (`clojure.core.memoize/fifo`) 10 | - Least-recently-used (`clojure.core.memoize/lru`) 11 | - Least-used (`clojure.core.memoize/lu`) 12 | - Time-to-live (`clojure.core.memoize/ttl`) 13 | - Naive cache (`memo`) that duplicates the functionality of Clojure's `memoize` function _but, unlike the built-in `memoize` function, ensures that in the case of concurrent calls with the same arguments, the memoized function is only invoked once_; in addition `memo` can use metadata from the memoized function to ignore certain arguments for the purpose of creating the cache key, e.g., allowing you to memoize `clojure.java.jdbc` functions where the first argument includes a (mutable) JDBC `Connection` object by specifying `:clojure.core.memoize/args-fn rest` in the metadata 14 | 15 | * Functions for manipulating the memoization cache of `core.memoize` backed functions 16 | 17 | 18 | 19 | Releases and Dependency Information 20 | ======================================== 21 | 22 | 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. 23 | 24 | Latest stable release: 1.1.266 25 | 26 | * [All Released Versions](https://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22org.clojure%22%20AND%20a%3A%22core.memoize%22) 27 | * [Development Snapshot Versions](https://oss.sonatype.org/index.html#nexus-search;gav~org.clojure~core.memoize~~~) 28 | 29 | [CLI/`deps.edn`](https://clojure.org/reference/deps_and_cli) dependency information: 30 | ```clojure 31 | org.clojure/core.memoize {:mvn/version "1.1.266"} 32 | ``` 33 | 34 | [Leiningen](https://github.com/technomancy/leiningen) dependency information: 35 | 36 | [org.clojure/core.memoize "1.1.266"] 37 | 38 | [Maven](https://maven.apache.org/) dependency information: 39 | 40 | 41 | org.clojure 42 | core.memoize 43 | 1.1.266 44 | 45 | 46 | Documentation 47 | ======================================== 48 | 49 | * [Auto-generated API docs](https://clojure.github.io/core.memoize/) 50 | * [core.memoize on cljdoc.org](https://cljdoc.org/d/org.clojure/core.memoize/) 51 | 52 | 53 | Example Usage 54 | ======================================== 55 | 56 | ```clojure 57 | (ns my.cool.lib 58 | (:require clojure.core.memoize)) 59 | 60 | (def id (clojure.core.memoize/lu 61 | #(do (Thread/sleep 5000) (identity %)) 62 | :lu/threshold 3)) 63 | 64 | (id 42) 65 | ; ... waits 5 seconds 66 | ;=> 42 67 | 68 | (id 42) 69 | ; instantly 70 | ;=> 42 71 | ``` 72 | 73 | Refer to docstrings in the `clojure.core.memoize` namespace for more information. 74 | 75 | 76 | 77 | Developer Information 78 | ======================================== 79 | 80 | * [GitHub project](https://github.com/clojure/core.memoize) 81 | * [Bug Tracker](https://clojure.atlassian.net/browse/CMEMOIZE) 82 | * [Continuous Integration](https://github.com/clojure/core.memoize/actions/workflows/test.yml) 83 | 84 | 85 | Change Log 86 | ==================== 87 | * Release 1.1.266 on 2024.02.19 88 | * Update parent pom and deps 89 | * Fixes [CMEMOIZE-30](https://clojure.atlassian.net/browse/CMEMOIZE-30) - typo in `ttl` docstring (j-mckitrick). 90 | * Release 1.0.257 on 2022.02.11 91 | * Implement `IPending` for `RetryingDelay` for folks trying to do low-level availability tests on long-running memoized functions. 92 | * Release 1.0.253 on 2021.12.06 93 | * Update `core.cache` to 1.0.225 94 | * Release 1.0.250 on 2021.08.02 95 | * Clarify differences between `clojure.core/memoize` and `clojure.core.memoize/memo` functions [CMEMOIZE-25](https://clojure.atlassian.net/browse/CMEMOIZE-25). 96 | * Update `core.cache` to 1.0.217. 97 | * Release 1.0.236 on 2020.04.13 98 | * Switch to 1.0.x versioning [CMEMOIZE-29](https://clojure.atlassian.net/browse/CMEMOIZE-29). 99 | * Update `core.cache` dependency version from 0.8.2 to 1.0.207. 100 | * Fixes [CMEMOIZE-9](https://clojure.atlassian.net/browse/CMEMOIZE-9) - adds `memo-reset!` and deprecates 2-arity version of `memo-swap!`; adds 3+-arity version of `memo-swap!` to behave more like a `swap!` operation on the underlying cache 101 | * Release 0.8.2 on 2019.11.01 (to match core.cache again) 102 | * Update `core.cache` dependency version from 0.7.2 to 0.8.2. 103 | * Fixes [CMEMOIZE-28](https://clojure.atlassian.net/browse/CMEMOIZE-28) - provides `memoizer` as a more convenient way to build custom cached functions that may provide a seed hash map of arguments to return values. `build-memoizer` should be considered deprecated at this point. 104 | * Fixes [CMEMOIZE-27](https://clojure.atlassian.net/browse/CMEMOIZE-27) - the `seed` function on `PluggableMemoization` now makes elements derefable (this case was missed when [CMEMOIZE-18](https://clojure.atlassian.net/browse/CMEMOIZE-18) was fixed) 105 | * Release 0.7.2 on 2019.06.13 106 | * Fixes [CMEMOIZE-26](https://clojure.atlassian.net/browse/CMEMOIZE-26) - zero-arity function cache could not be replaced by `memo-swap!` (discovered by Teemu Kaukoranta) 107 | * Updated core.cache dependency version from 0.7.1 to 0.7.2 108 | * Updated test matrix locally to include Clojure 1.10.1, 1.11 master 109 | * Release 0.7.1 on 2018.03.02 110 | * Fixes [CMEMOIZE-15](https://clojure.atlassian.net/browse/CMEMOIZE-15) - edge case where cache miss/lookup cross an eviction boundary (Ryan Fowler/Colin Jones) 111 | * Updated core.cache dependency version from 0.7.0 to 0.7.1 (for TTLCacheQ bug fix) 112 | * Release 0.7.0 on 2018.03.01 113 | * Fixes [CMEMOIZE-22](https://clojure.atlassian.net/browse/CMEMOIZE-22) - add `:clojure.core.memoize/args-fn` metadata support for memoizing functions which have one or more arguments that should not contribute to the cache key for calls 114 | * Fixes [CMEMOIZE-20](https://clojure.atlassian.net/browse/CMEMOIZE-20) - add `lazy-snapshot` function 115 | * Fixes [CMEMOIZE-18](https://clojure.atlassian.net/browse/CMEMOIZE-18) - automatically makes seed map values `deref`-able to match documentation and comply with core.memoize's world view 116 | * Cleanup/improve/fix tests 117 | * Add multi-version testing locally via Leiningen 118 | * Jump to 0.7.0 to match core.cache since these two libraries are so closely in sync 119 | * Release 0.5.9 on 2016.03.28 120 | * Updated core.cache dependency version from 0.6.4 to 0.6.5 121 | * Release 0.5.8 on 2015.11.06 122 | * Fixes [CMEMOIZE-21](https://clojure.atlassian.net/browse/CMEMOIZE-21) - race condition in delay 123 | * Release 0.5.7 on 2015.01.12 124 | * Fixes [CMEMOIZE-8](https://clojure.atlassian.net/browse/CMEMOIZE-8) 125 | * Fixes [CMEMOIZE-13](https://clojure.atlassian.net/browse/CMEMOIZE-13) 126 | * Updated core.cache dependency version from 0.6.3 to 0.6.4 127 | * Release 0.5.6 on 2013.06.28 128 | * Added optional args to `memo-clear!`. 129 | * Widened contract on factory functions to accept any callable. 130 | * Release 0.5.5 on 2013.06.14 131 | * Deprecated `memo-*` APIs 132 | * Adds new API of form `(cache-type function <:cache-type/threshold int>)` 133 | * Release 0.5.4 on 2013.06.03 134 | * Fixes [CMEMOIZE-5](https://clojure.atlassian.net/browse/CMEMOIZE-5) 135 | * Fixes [CMEMOIZE-2](https://clojure.atlassian.net/browse/CMEMOIZE-2) 136 | * Release 0.5.3 on 2013.03.18 137 | * Works with core.cache v0.6.3 138 | * Release 0.5.2 on 2012.07.13 139 | * Works with core.cache v0.6.1 140 | * Release 0.5.1 on 2011.12.13 141 | * Removed SoftCache memoization 142 | * Release 0.5.0 on 2011.12.13 143 | * Rolled in basis of Unk 144 | 145 | 146 | Copyright and License 147 | ======================================== 148 | 149 | Copyright (c) Rich Hickey and Michael Fogus, 2023. All rights reserved. The use and distribution terms for this software are covered by the Eclipse Public License 1.0 (https://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. 150 | -------------------------------------------------------------------------------- /src/test/clojure/clojure/core/memoize_test.clj: -------------------------------------------------------------------------------- 1 | ; Copyright (c) Rich Hickey and Michael Fogus. All rights reserved. 2 | ; The use and distribution terms for this software are covered by the 3 | ; Eclipse Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php) 4 | ; which can be found in the file epl-v10.html at the root of this distribution. 5 | ; By using this software in any fashion, you are agreeing to be bound by 6 | ; the terms of this license. 7 | ; You must not remove this notice, or any other, from this software. 8 | 9 | (ns ^{:doc "A memoization library for Clojure." 10 | :author "Michael Fogus"} 11 | clojure.core.memoize-test 12 | (:use [clojure.test] 13 | [clojure.core.cache :only [defcache lookup has? hit miss seed ttl-cache-factory]] 14 | [clojure.core.memoize])) 15 | 16 | (println "\nTesting with Clojure" (clojure-version)) 17 | 18 | (def id (memo identity)) 19 | 20 | (defn- check-core-features 21 | [factory] 22 | (let [mine (factory identity) 23 | them (memoize identity)] 24 | (testing "That the memo function works the same as core.memoize" 25 | (are [x y] = 26 | (mine 42) (them 42) 27 | (mine ()) (them ()) 28 | (mine []) (them []) 29 | (mine #{}) (them #{}) 30 | (mine {}) (them {}) 31 | (mine nil) (them nil))) 32 | (testing "That the memo function has a proper cache" 33 | (is (memoized? mine)) 34 | (is (not (memoized? them))) 35 | (is (= 42 (mine 42))) 36 | (is (not (empty? (snapshot mine)))) 37 | (is (not (empty? (lazy-snapshot mine)))) 38 | (is (memo-clear! mine)) 39 | (is (empty? (snapshot mine))) 40 | (is (empty? (lazy-snapshot mine))))) 41 | (testing "That the cache retries in case of exceptions" 42 | (let [access-count (atom 0) 43 | f (factory 44 | (fn [] 45 | (swap! access-count inc) 46 | (throw (Exception.))))] 47 | (is (thrown? Exception (f))) 48 | (is (thrown? Exception (f))) 49 | (is (= 2 @access-count)))) 50 | (testing "That the memo function does not have a race condition" 51 | (let [access-count (atom 0) 52 | slow-identity 53 | (factory (fn [x] 54 | (swap! access-count inc) 55 | (Thread/sleep 100) 56 | x))] 57 | (every? identity (pvalues (slow-identity 5) (slow-identity 5))) 58 | (is (= @access-count 1))))) 59 | 60 | (deftest test-memo 61 | (check-core-features memo)) 62 | 63 | 64 | (deftest test-fifo 65 | (let [mine (fifo identity :fifo/threshold 2)] 66 | ;; First check that the basic memo behavior holds 67 | (check-core-features #(fifo % :fifo/threshold 10)) 68 | 69 | ;; Now check FIFO-specific behavior 70 | (testing "that when the limit threshold is not breached, the cache works like the basic version" 71 | (are [x y] = 72 | 42 (mine 42) 73 | {[42] 42} (snapshot mine) 74 | 43 (mine 43) 75 | {[42] 42, [43] 43} (snapshot mine) 76 | 42 (mine 42) 77 | {[42] 42, [43] 43} (snapshot mine) 78 | [[42] 42, [43] 43] (lazy-snapshot mine))) 79 | (testing "that when the limit is breached, the oldest value is dropped" 80 | (are [x y] = 81 | 44 (mine 44) 82 | {[44] 44, [43] 43} (snapshot mine) 83 | [[44] 44, [43] 43] (lazy-snapshot mine))))) 84 | 85 | (deftest test-lru 86 | ;; First check that the basic memo behavior holds 87 | (check-core-features #(lru % :lru/threshold 10)) 88 | 89 | ;; Now check LRU-specific behavior 90 | (let [mine (lru identity)] 91 | (are [x y] = 92 | 42 (mine 42) 93 | 43 (mine 43) 94 | {[42] 42, [43] 43} (snapshot mine) 95 | 44 (mine 44) 96 | {[44] 44, [43] 43} (snapshot mine) 97 | 43 (mine 43) 98 | 0 (mine 0) 99 | {[0] 0, [43] 43} (snapshot mine) 100 | [[0] 0, [43] 43] (lazy-snapshot mine)))) 101 | 102 | 103 | (deftest test-ttl 104 | ;; First check that the basic memo behavior holds 105 | (check-core-features #(ttl % :ttl/threshold 2000)) 106 | 107 | ;; Now check TTL-specific behavior 108 | (let [mine (ttl identity :ttl/threshold 2000)] 109 | (are [x y] = 110 | 42 (mine 42) 111 | {[42] 42} (snapshot mine)) 112 | (Thread/sleep 3000) 113 | (are [x y] = 114 | 43 (mine 43) 115 | {[43] 43} (snapshot mine) 116 | [[43] 43] (lazy-snapshot mine))) 117 | 118 | ;; CMEMOIZE-15 edge case where TTLCache expires on miss/lookup 119 | (let [mine (ttl identity :ttl/threshold 5) 120 | limit 2000000 121 | start (System/currentTimeMillis)] 122 | (loop [n 0] 123 | (if-not (mine 42) 124 | (do 125 | (is false (str "Failure on call " n))) 126 | (if (< n limit) 127 | (recur (+ 1 n))))) 128 | (println "ttl test completed" limit "calls in" 129 | (- (System/currentTimeMillis) start) "ms"))) 130 | 131 | 132 | (deftest test-lu 133 | ;; First check that the basic memo behavior holds 134 | (check-core-features #(lu % :lu/threshold 10)) 135 | 136 | ;; Now check LU-specific behavior 137 | (let [mine (lu identity :lu/threshold 3)] 138 | (are [x y] = 139 | 42 (mine 42) 140 | 42 (mine 42) 141 | 43 (mine 43) 142 | 44 (mine 44) 143 | {[44] 44, [42] 42} (snapshot mine) 144 | [[44] 44, [42] 42] (lazy-snapshot mine)))) 145 | 146 | 147 | (defcache PassThrough [impl] 148 | clojure.core.cache/CacheProtocol 149 | (lookup [_ item] 150 | (if (has? impl item) 151 | (lookup impl item) 152 | (delay nil))) 153 | (has? [_ item] 154 | (clojure.core.cache/has? impl item)) 155 | (hit [this item] 156 | (PassThrough. (hit impl item))) 157 | (miss [this item result] 158 | (PassThrough. (miss impl item result))) 159 | (seed [_ base] 160 | (PassThrough. (seed impl base)))) 161 | 162 | (defn memo-pass-through-1 [f limit] 163 | (build-memoizer 164 | #(clojure.core.memoize.PluggableMemoization. %1 (PassThrough. (ttl-cache-factory %3 :ttl %2))) 165 | f 166 | limit 167 | {})) 168 | 169 | (deftest test-snapshot-without-cache-field-1 170 | (testing "that we can call snapshot against an object without a 'cache' field" 171 | (is (= {} (snapshot (memo-pass-through-1 identity 2000)))))) 172 | 173 | (defn memo-pass-through-2 [f limit] 174 | (memoizer f (PassThrough. (ttl-cache-factory {} :ttl limit)))) 175 | 176 | (deftest test-snapshot-without-cache-field-2 177 | (testing "that we can call snapshot against an object without a 'cache' field" 178 | (is (= {} (snapshot (memo-pass-through-2 identity 2000)))))) 179 | 180 | (deftest test-memoization-utils 181 | (let [CACHE_IDENTITY (:clojure.core.memoize/cache (meta id))] 182 | (testing "that the stored cache is not null" 183 | (is (not= nil CACHE_IDENTITY))) 184 | (testing "that a populated function looks correct at its inception" 185 | (is (memoized? id)) 186 | (is (snapshot id)) 187 | (is (empty? (snapshot id)))) 188 | (testing "that a populated function looks correct after some interactions" 189 | ;; Memoize once 190 | (is (= 42 (id 42))) 191 | ;; Now check to see if it looks right. 192 | (is (find (snapshot id) '(42))) 193 | (is (= 1 (count (snapshot id)))) 194 | ;; Memoize again 195 | (is (= [] (id []))) 196 | (is (find (snapshot id) '([]))) 197 | (is (= 2 (count (snapshot id)))) 198 | (testing "that upon memoizing again, the cache should not change" 199 | (is (= [] (id []))) 200 | (is (find (snapshot id) '([]))) 201 | (is (= 2 (count (snapshot id))))) 202 | (testing "if clearing the cache works as expected" 203 | (is (memo-clear! id)) 204 | (is (empty? (snapshot id))))) 205 | (testing "that after all manipulations, the cache maintains its identity" 206 | (is (identical? CACHE_IDENTITY (:clojure.core.memoize/cache (meta id))))) 207 | (testing "that a cache can be swapped and used normally" 208 | (is (memo-swap! id clojure.core.cache/miss [42] 42)) 209 | (is (= 42 (id 42))) 210 | (is (= {[42] 42} (snapshot id))) 211 | (is (= 108 (id 108))) 212 | (is (= {[42] 42 [108] 108} (snapshot id)))) 213 | (testing "that a cache can be seeded and used normally" 214 | (is (memo-reset! id {[42] 42})) 215 | (is (= 42 (id 42))) 216 | (is (= {[42] 42} (snapshot id))) 217 | (is (= 108 (id 108))) 218 | (is (= {[42] 42 [108] 108} (snapshot id)))) 219 | (testing "that we can get back the original function" 220 | (is (memo-clear! id)) 221 | (is (memo-reset! id {[42] 24})) 222 | (is (= 24 (id 42))) 223 | (is (= 42 ((memo-unwrap id) 42)))) 224 | (testing "that a cache can be seeded and used normally - deprecated memo-swap!" 225 | (is (memo-swap! id {[42] 42})) 226 | (is (= 42 (id 42))) 227 | (is (= {[42] 42} (snapshot id))) 228 | (is (= 108 (id 108))) 229 | (is (= {[42] 42 [108] 108} (snapshot id)))) 230 | (testing "that we can get back the original function - deprecated memo-swap!" 231 | (is (memo-clear! id)) 232 | (is (memo-swap! id {[42] 24})) 233 | (is (= 24 (id 42))) 234 | (is (= 42 ((memo-unwrap id) 42)))))) 235 | 236 | (deftest memo-with-seed-cmemoize-18 237 | (let [mine (memo identity {[42] 99})] 238 | (testing "that a memo seed works" 239 | (is (= 41 (mine 41))) 240 | (is (= 99 (mine 42))) 241 | (is (= 43 (mine 43))) 242 | (is (= {[41] 41, [42] 99, [43] 43} (snapshot mine))) 243 | (are [x y] = 244 | [[41] 41, [42] 99, [43] 43] (lazy-snapshot mine))))) 245 | 246 | (defn- ^{:clojure.core.memoize/args-fn rest} 247 | ignores-first-arg 248 | "Even tho' this adds all three arguments, we're going to cache it as if 249 | the first argument is irrelevant, so we can verify that the cache will 250 | collapse the argument space." 251 | [a b c] 252 | (+ a b c)) 253 | 254 | (deftest memo-with-args-fn-cmemoize-22 255 | ;; must use var to preserve metadata 256 | (let [mine (memo #'ignores-first-arg)] 257 | (testing "that args-fn collapses the cache key space" 258 | (is (= 13 (mine 1 2 10))) 259 | (is (= 13 (mine 10 2 1))) 260 | (is (= 13 (mine 10 2 10))) 261 | (is (= {[2 10] 13, [2 1] 13} (snapshot mine)))))) 262 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Eclipse Public License - v 1.0 2 | 3 | THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE PUBLIC 4 | LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THE PROGRAM 5 | CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT. 6 | 7 | 1. DEFINITIONS 8 | 9 | "Contribution" means: 10 | 11 | a) in the case of the initial Contributor, the initial code and documentation 12 | distributed under this Agreement, and 13 | b) in the case of each subsequent Contributor: 14 | i) changes to the Program, and 15 | ii) additions to the Program; 16 | 17 | where such changes and/or additions to the Program originate from and are 18 | distributed by that particular Contributor. A Contribution 'originates' 19 | from a Contributor if it was added to the Program by such Contributor 20 | itself or anyone acting on such Contributor's behalf. Contributions do not 21 | include additions to the Program which: (i) are separate modules of 22 | software distributed in conjunction with the Program under their own 23 | license agreement, and (ii) are not derivative works of the Program. 24 | 25 | "Contributor" means any person or entity that distributes the Program. 26 | 27 | "Licensed Patents" mean patent claims licensable by a Contributor which are 28 | necessarily infringed by the use or sale of its Contribution alone or when 29 | combined with the Program. 30 | 31 | "Program" means the Contributions distributed in accordance with this 32 | Agreement. 33 | 34 | "Recipient" means anyone who receives the Program under this Agreement, 35 | including all Contributors. 36 | 37 | 2. GRANT OF RIGHTS 38 | a) Subject to the terms of this Agreement, each Contributor hereby grants 39 | Recipient a non-exclusive, worldwide, royalty-free copyright license to 40 | reproduce, prepare derivative works of, publicly display, publicly 41 | perform, distribute and sublicense the Contribution of such Contributor, 42 | if any, and such derivative works, in source code and object code form. 43 | b) Subject to the terms of this Agreement, each Contributor hereby grants 44 | Recipient a non-exclusive, worldwide, royalty-free patent license under 45 | Licensed Patents to make, use, sell, offer to sell, import and otherwise 46 | transfer the Contribution of such Contributor, if any, in source code and 47 | object code form. This patent license shall apply to the combination of 48 | the Contribution and the Program if, at the time the Contribution is 49 | added by the Contributor, such addition of the Contribution causes such 50 | combination to be covered by the Licensed Patents. The patent license 51 | shall not apply to any other combinations which include the Contribution. 52 | No hardware per se is licensed hereunder. 53 | c) Recipient understands that although each Contributor grants the licenses 54 | to its Contributions set forth herein, no assurances are provided by any 55 | Contributor that the Program does not infringe the patent or other 56 | intellectual property rights of any other entity. Each Contributor 57 | disclaims any liability to Recipient for claims brought by any other 58 | entity based on infringement of intellectual property rights or 59 | otherwise. As a condition to exercising the rights and licenses granted 60 | hereunder, each Recipient hereby assumes sole responsibility to secure 61 | any other intellectual property rights needed, if any. For example, if a 62 | third party patent license is required to allow Recipient to distribute 63 | the Program, it is Recipient's responsibility to acquire that license 64 | before distributing the Program. 65 | d) Each Contributor represents that to its knowledge it has sufficient 66 | copyright rights in its Contribution, if any, to grant the copyright 67 | license set forth in this Agreement. 68 | 69 | 3. REQUIREMENTS 70 | 71 | A Contributor may choose to distribute the Program in object code form under 72 | its own license agreement, provided that: 73 | 74 | a) it complies with the terms and conditions of this Agreement; and 75 | b) its license agreement: 76 | i) effectively disclaims on behalf of all Contributors all warranties 77 | and conditions, express and implied, including warranties or 78 | conditions of title and non-infringement, and implied warranties or 79 | conditions of merchantability and fitness for a particular purpose; 80 | ii) effectively excludes on behalf of all Contributors all liability for 81 | damages, including direct, indirect, special, incidental and 82 | consequential damages, such as lost profits; 83 | iii) states that any provisions which differ from this Agreement are 84 | offered by that Contributor alone and not by any other party; and 85 | iv) states that source code for the Program is available from such 86 | Contributor, and informs licensees how to obtain it in a reasonable 87 | manner on or through a medium customarily used for software exchange. 88 | 89 | When the Program is made available in source code form: 90 | 91 | a) it must be made available under this Agreement; and 92 | b) a copy of this Agreement must be included with each copy of the Program. 93 | Contributors may not remove or alter any copyright notices contained 94 | within the Program. 95 | 96 | Each Contributor must identify itself as the originator of its Contribution, 97 | if 98 | any, in a manner that reasonably allows subsequent Recipients to identify the 99 | originator of the Contribution. 100 | 101 | 4. COMMERCIAL DISTRIBUTION 102 | 103 | Commercial distributors of software may accept certain responsibilities with 104 | respect to end users, business partners and the like. While this license is 105 | intended to facilitate the commercial use of the Program, the Contributor who 106 | includes the Program in a commercial product offering should do so in a manner 107 | which does not create potential liability for other Contributors. Therefore, 108 | if a Contributor includes the Program in a commercial product offering, such 109 | Contributor ("Commercial Contributor") hereby agrees to defend and indemnify 110 | every other Contributor ("Indemnified Contributor") against any losses, 111 | damages and costs (collectively "Losses") arising from claims, lawsuits and 112 | other legal actions brought by a third party against the Indemnified 113 | Contributor to the extent caused by the acts or omissions of such Commercial 114 | Contributor in connection with its distribution of the Program in a commercial 115 | product offering. The obligations in this section do not apply to any claims 116 | or Losses relating to any actual or alleged intellectual property 117 | infringement. In order to qualify, an Indemnified Contributor must: 118 | a) promptly notify the Commercial Contributor in writing of such claim, and 119 | b) allow the Commercial Contributor to control, and cooperate with the 120 | Commercial Contributor in, the defense and any related settlement 121 | negotiations. The Indemnified Contributor may participate in any such claim at 122 | its own expense. 123 | 124 | For example, a Contributor might include the Program in a commercial product 125 | offering, Product X. That Contributor is then a Commercial Contributor. If 126 | that Commercial Contributor then makes performance claims, or offers 127 | warranties related to Product X, those performance claims and warranties are 128 | such Commercial Contributor's responsibility alone. Under this section, the 129 | Commercial Contributor would have to defend claims against the other 130 | Contributors related to those performance claims and warranties, and if a 131 | court requires any other Contributor to pay any damages as a result, the 132 | Commercial Contributor must pay those damages. 133 | 134 | 5. NO WARRANTY 135 | 136 | EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS PROVIDED ON AN 137 | "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR 138 | IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, 139 | NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Each 140 | Recipient is solely responsible for determining the appropriateness of using 141 | and distributing the Program and assumes all risks associated with its 142 | exercise of rights under this Agreement , including but not limited to the 143 | risks and costs of program errors, compliance with applicable laws, damage to 144 | or loss of data, programs or equipment, and unavailability or interruption of 145 | operations. 146 | 147 | 6. DISCLAIMER OF LIABILITY 148 | 149 | EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT NOR ANY 150 | CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, 151 | SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION 152 | LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 153 | CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 154 | ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE 155 | EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY 156 | OF SUCH DAMAGES. 157 | 158 | 7. GENERAL 159 | 160 | If any provision of this Agreement is invalid or unenforceable under 161 | applicable law, it shall not affect the validity or enforceability of the 162 | remainder of the terms of this Agreement, and without further action by the 163 | parties hereto, such provision shall be reformed to the minimum extent 164 | necessary to make such provision valid and enforceable. 165 | 166 | If Recipient institutes patent litigation against any entity (including a 167 | cross-claim or counterclaim in a lawsuit) alleging that the Program itself 168 | (excluding combinations of the Program with other software or hardware) 169 | infringes such Recipient's patent(s), then such Recipient's rights granted 170 | under Section 2(b) shall terminate as of the date such litigation is filed. 171 | 172 | All Recipient's rights under this Agreement shall terminate if it fails to 173 | comply with any of the material terms or conditions of this Agreement and does 174 | not cure such failure in a reasonable period of time after becoming aware of 175 | such noncompliance. If all Recipient's rights under this Agreement terminate, 176 | Recipient agrees to cease use and distribution of the Program as soon as 177 | reasonably practicable. However, Recipient's obligations under this Agreement 178 | and any licenses granted by Recipient relating to the Program shall continue 179 | and survive. 180 | 181 | Everyone is permitted to copy and distribute copies of this Agreement, but in 182 | order to avoid inconsistency the Agreement is copyrighted and may only be 183 | modified in the following manner. The Agreement Steward reserves the right to 184 | publish new versions (including revisions) of this Agreement from time to 185 | time. No one other than the Agreement Steward has the right to modify this 186 | Agreement. The Eclipse Foundation is the initial Agreement Steward. The 187 | Eclipse Foundation may assign the responsibility to serve as the Agreement 188 | Steward to a suitable separate entity. Each new version of the Agreement will 189 | be given a distinguishing version number. The Program (including 190 | Contributions) may always be distributed subject to the version of the 191 | Agreement under which it was received. In addition, after a new version of the 192 | Agreement is published, Contributor may elect to distribute the Program 193 | (including its Contributions) under the new version. Except as expressly 194 | stated in Sections 2(a) and 2(b) above, Recipient receives no rights or 195 | licenses to the intellectual property of any Contributor under this Agreement, 196 | whether expressly, by implication, estoppel or otherwise. All rights in the 197 | Program not expressly granted under this Agreement are reserved. 198 | 199 | This Agreement is governed by the laws of the State of New York and the 200 | intellectual property laws of the United States of America. No party to this 201 | Agreement will bring a legal action under this Agreement more than one year 202 | after the cause of action arose. Each party waives its rights to a jury trial in 203 | any resulting litigation. 204 | 205 | 206 | -------------------------------------------------------------------------------- /epl-v10.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | Eclipse Public License - Version 1.0 8 | 25 | 26 | 27 | 28 | 29 | 30 |

Eclipse Public License - v 1.0

31 | 32 |

THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE 33 | PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR 34 | DISTRIBUTION OF THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS 35 | AGREEMENT.

36 | 37 |

1. DEFINITIONS

38 | 39 |

"Contribution" means:

40 | 41 |

a) in the case of the initial Contributor, the initial 42 | code and documentation distributed under this Agreement, and

43 |

b) in the case of each subsequent Contributor:

44 |

i) changes to the Program, and

45 |

ii) additions to the Program;

46 |

where such changes and/or additions to the Program 47 | originate from and are distributed by that particular Contributor. A 48 | Contribution 'originates' from a Contributor if it was added to the 49 | Program by such Contributor itself or anyone acting on such 50 | Contributor's behalf. Contributions do not include additions to the 51 | Program which: (i) are separate modules of software distributed in 52 | conjunction with the Program under their own license agreement, and (ii) 53 | are not derivative works of the Program.

54 | 55 |

"Contributor" means any person or entity that distributes 56 | the Program.

57 | 58 |

"Licensed Patents" mean patent claims licensable by a 59 | Contributor which are necessarily infringed by the use or sale of its 60 | Contribution alone or when combined with the Program.

61 | 62 |

"Program" means the Contributions distributed in accordance 63 | with this Agreement.

64 | 65 |

"Recipient" means anyone who receives the Program under 66 | this Agreement, including all Contributors.

67 | 68 |

2. GRANT OF RIGHTS

69 | 70 |

a) Subject to the terms of this Agreement, each 71 | Contributor hereby grants Recipient a non-exclusive, worldwide, 72 | royalty-free copyright license to reproduce, prepare derivative works 73 | of, publicly display, publicly perform, distribute and sublicense the 74 | Contribution of such Contributor, if any, and such derivative works, in 75 | source code and object code form.

76 | 77 |

b) Subject to the terms of this Agreement, each 78 | Contributor hereby grants Recipient a non-exclusive, worldwide, 79 | royalty-free patent license under Licensed Patents to make, use, sell, 80 | offer to sell, import and otherwise transfer the Contribution of such 81 | Contributor, if any, in source code and object code form. This patent 82 | license shall apply to the combination of the Contribution and the 83 | Program if, at the time the Contribution is added by the Contributor, 84 | such addition of the Contribution causes such combination to be covered 85 | by the Licensed Patents. The patent license shall not apply to any other 86 | combinations which include the Contribution. No hardware per se is 87 | licensed hereunder.

88 | 89 |

c) Recipient understands that although each Contributor 90 | grants the licenses to its Contributions set forth herein, no assurances 91 | are provided by any Contributor that the Program does not infringe the 92 | patent or other intellectual property rights of any other entity. Each 93 | Contributor disclaims any liability to Recipient for claims brought by 94 | any other entity based on infringement of intellectual property rights 95 | or otherwise. As a condition to exercising the rights and licenses 96 | granted hereunder, each Recipient hereby assumes sole responsibility to 97 | secure any other intellectual property rights needed, if any. For 98 | example, if a third party patent license is required to allow Recipient 99 | to distribute the Program, it is Recipient's responsibility to acquire 100 | that license before distributing the Program.

101 | 102 |

d) Each Contributor represents that to its knowledge it 103 | has sufficient copyright rights in its Contribution, if any, to grant 104 | the copyright license set forth in this Agreement.

105 | 106 |

3. REQUIREMENTS

107 | 108 |

A Contributor may choose to distribute the Program in object code 109 | form under its own license agreement, provided that:

110 | 111 |

a) it complies with the terms and conditions of this 112 | Agreement; and

113 | 114 |

b) its license agreement:

115 | 116 |

i) effectively disclaims on behalf of all Contributors 117 | all warranties and conditions, express and implied, including warranties 118 | or conditions of title and non-infringement, and implied warranties or 119 | conditions of merchantability and fitness for a particular purpose;

120 | 121 |

ii) effectively excludes on behalf of all Contributors 122 | all liability for damages, including direct, indirect, special, 123 | incidental and consequential damages, such as lost profits;

124 | 125 |

iii) states that any provisions which differ from this 126 | Agreement are offered by that Contributor alone and not by any other 127 | party; and

128 | 129 |

iv) states that source code for the Program is available 130 | from such Contributor, and informs licensees how to obtain it in a 131 | reasonable manner on or through a medium customarily used for software 132 | exchange.

133 | 134 |

When the Program is made available in source code form:

135 | 136 |

a) it must be made available under this Agreement; and

137 | 138 |

b) a copy of this Agreement must be included with each 139 | copy of the Program.

140 | 141 |

Contributors may not remove or alter any copyright notices contained 142 | within the Program.

143 | 144 |

Each Contributor must identify itself as the originator of its 145 | Contribution, if any, in a manner that reasonably allows subsequent 146 | Recipients to identify the originator of the Contribution.

147 | 148 |

4. COMMERCIAL DISTRIBUTION

149 | 150 |

Commercial distributors of software may accept certain 151 | responsibilities with respect to end users, business partners and the 152 | like. While this license is intended to facilitate the commercial use of 153 | the Program, the Contributor who includes the Program in a commercial 154 | product offering should do so in a manner which does not create 155 | potential liability for other Contributors. Therefore, if a Contributor 156 | includes the Program in a commercial product offering, such Contributor 157 | ("Commercial Contributor") hereby agrees to defend and 158 | indemnify every other Contributor ("Indemnified Contributor") 159 | against any losses, damages and costs (collectively "Losses") 160 | arising from claims, lawsuits and other legal actions brought by a third 161 | party against the Indemnified Contributor to the extent caused by the 162 | acts or omissions of such Commercial Contributor in connection with its 163 | distribution of the Program in a commercial product offering. The 164 | obligations in this section do not apply to any claims or Losses 165 | relating to any actual or alleged intellectual property infringement. In 166 | order to qualify, an Indemnified Contributor must: a) promptly notify 167 | the Commercial Contributor in writing of such claim, and b) allow the 168 | Commercial Contributor to control, and cooperate with the Commercial 169 | Contributor in, the defense and any related settlement negotiations. The 170 | Indemnified Contributor may participate in any such claim at its own 171 | expense.

172 | 173 |

For example, a Contributor might include the Program in a commercial 174 | product offering, Product X. That Contributor is then a Commercial 175 | Contributor. If that Commercial Contributor then makes performance 176 | claims, or offers warranties related to Product X, those performance 177 | claims and warranties are such Commercial Contributor's responsibility 178 | alone. Under this section, the Commercial Contributor would have to 179 | defend claims against the other Contributors related to those 180 | performance claims and warranties, and if a court requires any other 181 | Contributor to pay any damages as a result, the Commercial Contributor 182 | must pay those damages.

183 | 184 |

5. NO WARRANTY

185 | 186 |

EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS 187 | PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 188 | OF ANY KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, 189 | ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY 190 | OR FITNESS FOR A PARTICULAR PURPOSE. Each Recipient is solely 191 | responsible for determining the appropriateness of using and 192 | distributing the Program and assumes all risks associated with its 193 | exercise of rights under this Agreement , including but not limited to 194 | the risks and costs of program errors, compliance with applicable laws, 195 | damage to or loss of data, programs or equipment, and unavailability or 196 | interruption of operations.

197 | 198 |

6. DISCLAIMER OF LIABILITY

199 | 200 |

EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT 201 | NOR ANY CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, 202 | INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING 203 | WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF 204 | LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 205 | NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OR 206 | DISTRIBUTION OF THE PROGRAM OR THE EXERCISE OF ANY RIGHTS GRANTED 207 | HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

208 | 209 |

7. GENERAL

210 | 211 |

If any provision of this Agreement is invalid or unenforceable under 212 | applicable law, it shall not affect the validity or enforceability of 213 | the remainder of the terms of this Agreement, and without further action 214 | by the parties hereto, such provision shall be reformed to the minimum 215 | extent necessary to make such provision valid and enforceable.

216 | 217 |

If Recipient institutes patent litigation against any entity 218 | (including a cross-claim or counterclaim in a lawsuit) alleging that the 219 | Program itself (excluding combinations of the Program with other 220 | software or hardware) infringes such Recipient's patent(s), then such 221 | Recipient's rights granted under Section 2(b) shall terminate as of the 222 | date such litigation is filed.

223 | 224 |

All Recipient's rights under this Agreement shall terminate if it 225 | fails to comply with any of the material terms or conditions of this 226 | Agreement and does not cure such failure in a reasonable period of time 227 | after becoming aware of such noncompliance. If all Recipient's rights 228 | under this Agreement terminate, Recipient agrees to cease use and 229 | distribution of the Program as soon as reasonably practicable. However, 230 | Recipient's obligations under this Agreement and any licenses granted by 231 | Recipient relating to the Program shall continue and survive.

232 | 233 |

Everyone is permitted to copy and distribute copies of this 234 | Agreement, but in order to avoid inconsistency the Agreement is 235 | copyrighted and may only be modified in the following manner. The 236 | Agreement Steward reserves the right to publish new versions (including 237 | revisions) of this Agreement from time to time. No one other than the 238 | Agreement Steward has the right to modify this Agreement. The Eclipse 239 | Foundation is the initial Agreement Steward. The Eclipse Foundation may 240 | assign the responsibility to serve as the Agreement Steward to a 241 | suitable separate entity. Each new version of the Agreement will be 242 | given a distinguishing version number. The Program (including 243 | Contributions) may always be distributed subject to the version of the 244 | Agreement under which it was received. In addition, after a new version 245 | of the Agreement is published, Contributor may elect to distribute the 246 | Program (including its Contributions) under the new version. Except as 247 | expressly stated in Sections 2(a) and 2(b) above, Recipient receives no 248 | rights or licenses to the intellectual property of any Contributor under 249 | this Agreement, whether expressly, by implication, estoppel or 250 | otherwise. All rights in the Program not expressly granted under this 251 | Agreement are reserved.

252 | 253 |

This Agreement is governed by the laws of the State of New York and 254 | the intellectual property laws of the United States of America. No party 255 | to this Agreement will bring a legal action under this Agreement more 256 | than one year after the cause of action arose. Each party waives its 257 | rights to a jury trial in any resulting litigation.

258 | 259 | 260 | 261 | 262 | -------------------------------------------------------------------------------- /src/main/clojure/clojure/core/memoize.clj: -------------------------------------------------------------------------------- 1 | ; Copyright (c) Rich Hickey and Michael Fogus. All rights reserved. 2 | ; The use and distribution terms for this software are covered by the 3 | ; Eclipse Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php) 4 | ; which can be found in the file epl-v10.html at the root of this distribution. 5 | ; By using this software in any fashion, you are agreeing to be bound by 6 | ; the terms of this license. 7 | ; You must not remove this notice, or any other, from this software. 8 | 9 | (ns clojure.core.memoize 10 | "core.memoize is a memoization library offering functionality above 11 | Clojure's core `memoize` function in the following ways: 12 | 13 | **Pluggable memoization** 14 | 15 | core.memoize allows for different back-end cache implmentations to 16 | be used as appropriate without changing the memoization modus operandi. 17 | See the `memoizer` function. 18 | 19 | **Manipulable memoization** 20 | 21 | Because core.memoize allows you to access a function's memoization store, 22 | you do interesting things like clear it, modify it, and save it for later. 23 | " 24 | {:author "fogus"} 25 | 26 | (:require [clojure.core.cache :as cache])) 27 | 28 | 29 | 30 | ;; Similar to clojure.lang.Delay, but will not memoize an exception and will 31 | ;; instead retry. 32 | ;; fun - the function, never nil 33 | ;; available? - indicates a memoized value is available, volatile for visibility 34 | ;; value - the value (if available) - volatile for visibility 35 | (deftype RetryingDelay [fun ^:volatile-mutable available? ^:volatile-mutable value] 36 | clojure.lang.IDeref 37 | (deref [this] 38 | ;; first check (safe with volatile flag) 39 | (if available? 40 | value 41 | (locking fun 42 | ;; second check (race condition with locking) 43 | (if available? 44 | value 45 | (do 46 | ;; fun may throw - will retry on next deref 47 | (let [v (fun)] 48 | ;; this ordering is important - MUST set value before setting available? 49 | ;; or you have a race with the first check above 50 | (set! value v) 51 | (set! available? true) 52 | v)))))) 53 | clojure.lang.IPending 54 | (isRealized [this] 55 | available?)) 56 | 57 | (defn- d-lay [fun] 58 | (->RetryingDelay fun false nil)) 59 | 60 | (defn- make-derefable 61 | "If a value is not already derefable, wrap it up. 62 | 63 | This is used to help rebuild seed/base maps passed in to the various 64 | caches so that they conform to core.memoize's world view." 65 | [v] 66 | (if (instance? clojure.lang.IDeref v) 67 | v 68 | (reify clojure.lang.IDeref 69 | (deref [_] v)))) 70 | 71 | (defn- derefable-seed 72 | "Given a seed/base map, ensure all the values in it are derefable." 73 | [seed] 74 | (into {} (for [[k v] seed] [k (make-derefable v)]))) 75 | 76 | ;; Plugging Interface 77 | 78 | (deftype PluggableMemoization [f cache] 79 | cache/CacheProtocol 80 | (has? [_ item] 81 | (clojure.core.cache/has? cache item)) 82 | (hit [_ item] 83 | (PluggableMemoization. f (clojure.core.cache/hit cache item))) 84 | (miss [_ item result] 85 | (PluggableMemoization. f (clojure.core.cache/miss cache item result))) 86 | (evict [_ key] 87 | (PluggableMemoization. f (clojure.core.cache/evict cache key))) 88 | (lookup [_ item] 89 | (clojure.core.cache/lookup cache item nil)) 90 | (lookup [_ item not-found] 91 | (clojure.core.cache/lookup cache item (delay not-found))) 92 | (seed [_ base] 93 | (PluggableMemoization. 94 | f (clojure.core.cache/seed cache (derefable-seed base)))) 95 | Object 96 | (toString [_] (str cache))) 97 | 98 | ;; # Auxilliary functions 99 | 100 | (def ^{:private true 101 | :doc "Returns a function's argument transformer."} 102 | args-fn #(or (::args-fn (meta %)) identity)) 103 | 104 | (defn- through* 105 | "The basic hit/miss logic for the cache system based on `core.cache/through`. 106 | Clojure delays are used to hold the cache value." 107 | [cache f args item] 108 | (clojure.core.cache/through 109 | (fn [f _] (d-lay #(f args))) 110 | #(clojure.core/apply f %) 111 | cache 112 | item)) 113 | 114 | (def ^{:private true 115 | :doc "Returns a function's cache identity."} 116 | cache-id #(::cache (meta %))) 117 | 118 | 119 | ;; # Public Utilities API 120 | 121 | (defn snapshot 122 | "Returns a snapshot of a core.memo-placed memoization cache. By snapshot 123 | you can infer that what you get is only the cache contents at a 124 | moment in time." 125 | [memoized-fn] 126 | (when-let [cache (cache-id memoized-fn)] 127 | (into {} 128 | (for [[k v] (.cache ^PluggableMemoization @cache)] 129 | [(vec k) @v])))) 130 | 131 | (defn lazy-snapshot 132 | "Returns a lazy snapshot of a core.memo-placed memoization cache. By 133 | lazy snapshot you can infer that what you get is only the cache contents at a 134 | moment in time -- and, being lazy, the cache could change while you are 135 | realizing the snapshot elements. 136 | 137 | Returns a sequence of key/value pairs." 138 | [memoized-fn] 139 | (when-let [cache (cache-id memoized-fn)] 140 | (for [[k v] (.cache ^PluggableMemoization @cache)] 141 | [(vec k) @v]))) 142 | 143 | (defn memoized? 144 | "Returns true if a function has an core.memo-placed cache, false otherwise." 145 | [f] 146 | (boolean (cache-id f))) 147 | 148 | (defn memo-clear! 149 | "Reaches into an core.memo-memoized function and clears the cache. This is a 150 | destructive operation and should be used with care. 151 | 152 | When the second argument is a vector of input arguments, clears cache only 153 | for argument vector. 154 | 155 | Keep in mind that depending on what other threads or doing, an 156 | immediate call to `snapshot` may not yield an empty cache. That's 157 | cool though, we've learned to deal with that stuff in Clojure by 158 | now." 159 | ([f] 160 | (when-let [cache (cache-id f)] 161 | (swap! cache (constantly (clojure.core.cache/seed @cache {}))))) 162 | ([f args] 163 | (when-let [cache (cache-id f)] 164 | (swap! cache (constantly (clojure.core.cache/evict @cache args)))))) 165 | 166 | (defn memo-reset! 167 | "Takes a core.memo-populated function and a map and replaces the memoization cache 168 | with the supplied map. This is potentially some serious voodoo, 169 | since you can effectively change the semantics of a function on the fly. 170 | 171 | (def id (memo identity)) 172 | (memo-swap! id '{[13] :omg}) 173 | (id 13) 174 | ;=> :omg 175 | 176 | With great power comes ... yadda yadda yadda." 177 | [f base] 178 | (when-let [cache (cache-id f)] 179 | (swap! cache 180 | (constantly (clojure.core.cache/seed @cache (derefable-seed base)))))) 181 | 182 | (defn memo-swap! 183 | "The 2-arity version takes a core.memo-populated function and a map and 184 | replaces the memoization cache with the supplied map. Use `memo-reset!` 185 | instead for replacing the cache as this 2-arity version of `memo-swap!` 186 | should be considered deprecated. 187 | 188 | The 3+-arity version takes a core.memo-populated function and arguments 189 | similar to what you would pass to `clojure.core/swap!` and performs a 190 | `swap!` on the underlying cache. In order to satisfy core.memoize's 191 | world view, the assumption is that you will generally be calling it like: 192 | 193 | (def id (memo identity)) 194 | (memo-swap! id clojure.core.cache/miss [13] :omg) 195 | (id 13) 196 | ;=> :omg 197 | 198 | You'll nearly always use `clojure.core.cache/miss` for this operation but 199 | you could pass any function that would work on an immutable cache, such 200 | as `evict` or `assoc` etc. 201 | 202 | Be aware that `memo-swap!` assumes it can wrap each of the `results` values 203 | in a `delay` so that items conform to `clojure.core.memoize`'s world view." 204 | ([f base] 205 | (when-let [cache (cache-id f)] 206 | (swap! cache 207 | (constantly (clojure.core.cache/seed @cache (derefable-seed base)))))) 208 | ([f swap-fn args & results] 209 | (when-let [cache (cache-id f)] 210 | (apply swap! cache swap-fn args (map #(delay %) results))))) 211 | 212 | (defn memo-unwrap 213 | [f] 214 | (::original (meta f))) 215 | 216 | (defn- cached-function 217 | "Given a function, an atom containing a (pluggable memoization cache), and 218 | and cache key function, return a new function that behaves like the original 219 | function except it is cached, based on its arguments, with the cache and the 220 | original function in its metadata." 221 | [f cache-atom ckey-fn] 222 | (with-meta 223 | (fn [& args] 224 | (let [ckey (or (ckey-fn args) []) 225 | cs (swap! cache-atom through* f args ckey) 226 | val (clojure.core.cache/lookup cs ckey ::not-found)] 227 | ;; If `lookup` returns `(delay ::not-found)`, it's likely that 228 | ;; we ran into a timing issue where eviction and access 229 | ;; are happening at about the same time. Therefore, we retry 230 | ;; the `swap!` (potentially several times). 231 | ;; 232 | ;; core.memoize currently wraps all of its values in a `delay`. 233 | (when val 234 | (loop [n 0 v @val] 235 | (if (= ::not-found v) 236 | (when-let [v' (clojure.core.cache/lookup 237 | (swap! cache-atom through* f args ckey) 238 | ckey ::not-found)] 239 | (when (< n 10) 240 | (recur (inc n) @v'))) 241 | v))))) 242 | {::cache cache-atom 243 | ::original f})) 244 | 245 | ;; # Public memoization API 246 | 247 | (defn memoizer 248 | "Build a pluggable memoized version of a function. Given a function and a 249 | (pluggable memoized) cache, and an optional seed (hash map of arguments to 250 | return values), return a cached version of that function. 251 | 252 | If you want to build your own cached function, perhaps with combined caches 253 | or customized caches, this is the preferred way to do so now." 254 | ([f cache] 255 | (let [cache (atom (PluggableMemoization. f cache)) 256 | ckey-fn (args-fn f)] 257 | (cached-function f cache ckey-fn))) 258 | ([f cache seed] 259 | (let [cache (atom (clojure.core.cache/seed (PluggableMemoization. f cache) 260 | (derefable-seed seed))) 261 | ckey-fn (args-fn f)] 262 | (cached-function f cache ckey-fn)))) 263 | 264 | (defn build-memoizer 265 | "Builds a function that, given a function, returns a pluggable memoized 266 | version of it. `build-memoizer` takes a cache factory function, and the 267 | arguments to that factory function -- at least one of those arguments 268 | should be the function to be memoized (it's usually the first argument). 269 | 270 | `memoizer` above is a simpler version of `build-memoizer` that 'does the 271 | right thing' with a cache and a seed hash map. `build-memoizer` remains 272 | for backward compatibility but should be considered deprecated." 273 | ([cache-factory f & args] 274 | (let [cache (atom (apply cache-factory f args)) 275 | ckey-fn (args-fn f)] 276 | (cached-function f cache ckey-fn)))) 277 | 278 | (defn memo 279 | "Used as a more flexible alternative to Clojure's core `memoization` 280 | function. Memoized functions built using `memo` will respond to 281 | the core.memo manipulable memoization utilities. As a nice bonus, 282 | you can use `memo` in place of `memoize` without any additional 283 | changes, with the added guarantee that the memoized function will 284 | only be called once for a given sequence of arguments (`memoize` 285 | can call the function multiple times when concurrent calls are 286 | made with the same sequence of arguments). 287 | 288 | The default way to use this function is to simply supply a function 289 | that will be memoized. Additionally, you may also supply a map 290 | of the form `'{[42] 42, [108] 108}` where keys are a vector 291 | mapping expected argument values to arity positions. The map values 292 | are the return values of the memoized function. 293 | 294 | If the supplied function has metadata containing an 295 | `:clojure.core.memoize/args-fn` key, the value is assumed to be a 296 | function that should be applied to the arguments to produce a 297 | subset or transformed sequence of arguments that are used for the 298 | key in the cache (the full, original arguments will still be used 299 | to call the function). This allows you to memoize functions where 300 | one or more arguments are irrelevant for memoization, such as the 301 | `clojure.java.jdbc` functions, whose first argument may include 302 | a (mutable) JDBC `Connection` object: 303 | 304 | (memo/memo (with-meta jdbc/execute! {::memo/args-fn rest})) 305 | 306 | You can access the memoization cache directly via the `:clojure.core.memoize/cache` key 307 | on the memoized function's metadata. However, it is advised to 308 | use the core.memo primitives instead as implementation details may 309 | change over time." 310 | ([f] (memo f {})) 311 | ([f seed] 312 | (memoizer f (cache/basic-cache-factory {}) seed))) 313 | 314 | ;; ## Utilities 315 | 316 | (defn ^{:private true} !! [c] 317 | (println "WARNING - Deprecated construction method for" 318 | c 319 | "cache; prefered way is:" 320 | (str "(clojure.core.memoize/" c " function <:" c "/threshold num>)"))) 321 | 322 | (defmacro ^{:private true} def-deprecated [nom ds & arities] 323 | `(defn ~(symbol (str "memo-" (name nom))) ~ds 324 | ~@(for [[args body] arities] 325 | (list args `(!! (quote ~nom)) body)))) 326 | 327 | (defmacro ^{:private true} massert [condition msg] 328 | `(when-not ~condition 329 | (throw (new AssertionError (str "clojure.core.memoize/" ~msg "\n" (pr-str '~condition)))))) 330 | 331 | (defmacro ^{:private true} check-args [nom f base key threshold] 332 | (when *assert* 333 | (let [good-key (keyword nom "threshold") 334 | key-error `(str "Incorrect threshold key " ~key) 335 | fun-error `(str ~nom " expects a function as its first argument; given " ~f) 336 | thresh-error `(str ~nom " expects an integer for its " ~good-key " argument; given " ~threshold)] 337 | `(do (massert (= ~key ~good-key) ~key-error) 338 | (massert (some #{clojure.lang.IFn 339 | clojure.lang.AFn 340 | java.lang.Runnable 341 | java.util.concurrent.Callable} 342 | (ancestors (class ~f))) 343 | ~fun-error) 344 | (massert (number? ~threshold) ~thresh-error))))) 345 | 346 | ;; ## Main API functions 347 | 348 | ;; ### FIFO 349 | 350 | (def-deprecated fifo 351 | "DEPRECATED: Please use clojure.core.memoize/fifo instead." 352 | ([f] (memo-fifo f 32 {})) 353 | ([f limit] (memo-fifo f limit {})) 354 | ([f limit base] 355 | (memoizer f (cache/fifo-cache-factory {} :threshold limit) base))) 356 | 357 | (defn fifo 358 | "Works the same as the basic memoization function (i.e. `memo` 359 | and `core.memoize` except when a given threshold is breached. 360 | 361 | Observe the following: 362 | 363 | (require '[clojure.core.memoize :as memo]) 364 | 365 | (def id (memo/fifo identity :fifo/threshold 2)) 366 | 367 | (id 42) 368 | (id 43) 369 | (snapshot id) 370 | ;=> {[42] 42, [43] 43} 371 | 372 | As you see, the limit of `2` has not been breached yet, but 373 | if you call again with another value, then it is: 374 | 375 | (id 44) 376 | (snapshot id) 377 | ;=> {[44] 44, [43] 43} 378 | 379 | That is, the oldest entry `42` is pushed out of the 380 | memoization cache. This is the standard **F**irst **I**n 381 | **F**irst **O**ut behavior." 382 | ([f] (fifo f {} :fifo/threshold 32)) 383 | ([f base] (fifo f base :fifo/threshold 32)) 384 | ([f tkey threshold] (fifo f {} tkey threshold)) 385 | ([f base key threshold] 386 | (check-args "fifo" f base key threshold) 387 | (memoizer f (cache/fifo-cache-factory {} :threshold threshold) base))) 388 | 389 | ;; ### LRU 390 | 391 | (def-deprecated lru 392 | "DEPRECATED: Please use clojure.core.memoize/lru instead." 393 | ([f] (memo-lru f 32)) 394 | ([f limit] (memo-lru f limit {})) 395 | ([f limit base] 396 | (memoizer f (cache/lru-cache-factory {} :threshold limit) base))) 397 | 398 | (defn lru 399 | "Works the same as the basic memoization function (i.e. `memo` 400 | and `core.memoize` except when a given threshold is breached. 401 | 402 | Observe the following: 403 | 404 | (require '[clojure.core.memoize :as memo]) 405 | 406 | (def id (memo/lru identity :lru/threshold 2)) 407 | 408 | (id 42) 409 | (id 43) 410 | (snapshot id) 411 | ;=> {[42] 42, [43] 43} 412 | 413 | At this point the cache has not yet crossed the set threshold 414 | of `2`, but if you execute yet another call the story will 415 | change: 416 | 417 | (id 44) 418 | (snapshot id) 419 | ;=> {[44] 44, [43] 43} 420 | 421 | At this point the operation of the LRU cache looks exactly 422 | the same at the FIFO cache. However, the difference becomes 423 | apparent on further use: 424 | 425 | (id 43) 426 | (id 0) 427 | (snapshot id) 428 | ;=> {[0] 0, [43] 43} 429 | 430 | As you see, once again calling `id` with the argument `43` 431 | will expose the LRU nature of the underlying cache. That is, 432 | when the threshold is passed, the cache will expel the 433 | **L**east **R**ecently **U**sed element in favor of the new." 434 | ([f] (lru f {} :lru/threshold 32)) 435 | ([f base] (lru f base :lru/threshold 32)) 436 | ([f tkey threshold] (lru f {} tkey threshold)) 437 | ([f base key threshold] 438 | (check-args "lru" f base key threshold) 439 | (memoizer f (cache/lru-cache-factory {} :threshold threshold) base))) 440 | 441 | ;; ### TTL 442 | 443 | (def-deprecated ttl 444 | "DEPRECATED: Please use clojure.core.memoize/ttl instead." 445 | ([f] (memo-ttl f 3000 {})) 446 | ([f limit] (memo-ttl f limit {})) 447 | ([f limit base] 448 | (memoizer f (cache/ttl-cache-factory {} :ttl limit) base))) 449 | 450 | (defn ttl 451 | "Unlike many of the other core.memo memoization functions, 452 | `memo-ttl`'s cache policy is time-based rather than algorithmic 453 | or explicit. When memoizing a function using `memo-ttl` you 454 | should provide a **T**ime **T**o **L**ive parameter in 455 | milliseconds. 456 | 457 | (require '[clojure.core.memoize :as memo]) 458 | 459 | (def id (memo/ttl identity :ttl/threshold 5000)) 460 | 461 | (id 42) 462 | (snapshot id) 463 | ;=> {[42] 42} 464 | 465 | ... wait 5 seconds ... 466 | (id 43) 467 | (snapshot id) 468 | ;=> {[43] 43} 469 | 470 | The expired cache entries will be removed on each cache **miss**." 471 | ([f] (ttl f {} :ttl/threshold 32)) 472 | ([f base] (ttl f base :ttl/threshold 32)) 473 | ([f tkey threshold] (ttl f {} tkey threshold)) 474 | ([f base key threshold] 475 | (check-args "ttl" f base key threshold) 476 | (memoizer f (cache/ttl-cache-factory {} :ttl threshold) base))) 477 | 478 | ;; ### LU 479 | 480 | (def-deprecated lu 481 | "DEPRECATED: Please use clojure.core.memoize/lu instead." 482 | ([f] (memo-lu f 32)) 483 | ([f limit] (memo-lu f limit {})) 484 | ([f limit base] 485 | (memoizer f (cache/lu-cache-factory {} :threshold limit) base))) 486 | 487 | (defn lu 488 | "Similar to the implementation of memo-lru, except that this 489 | function removes all cache values whose usage value is 490 | smallest: 491 | 492 | (require '[clojure.core.memoize :as memo]) 493 | 494 | (def id (memo/lu identity :lu/threshold 3)) 495 | 496 | (id 42) 497 | (id 42) 498 | (id 43) 499 | (id 44) 500 | (snapshot id) 501 | ;=> {[44] 44, [42] 42} 502 | 503 | The **L**east **U**sed values are cleared on cache misses." 504 | ([f] (lu f {} :lu/threshold 32)) 505 | ([f base] (lu f base :lu/threshold 32)) 506 | ([f tkey threshold] (lu f {} tkey threshold)) 507 | ([f base key threshold] 508 | (check-args "lu" f base key threshold) 509 | (memoizer f (cache/lu-cache-factory {} :threshold threshold) base))) 510 | --------------------------------------------------------------------------------