SoftCaches update in-place, other cache types don't
I've successfully used SoftCaches in my project, and now I had the need for another simple cache, so I've created a BasicCache. Thereby, I fell into the trap that while SoftCaches update in-place, BasicCaches don't (and looking at the code, all other cache types except for aforementioned SoftCache don't, too).
So with every cache type except for SoftCaches, you have to use the return value of `miss` (and `evict`). But the documentation doesn't mention that at all. The typical has?/miss/hit snippets explaining the usage pattern also discard the value of `miss`.
IMHO, a cache is something mutable and should of course update in place. I mean, when you `(def C (some-cache...))`, are you really supposed to use `alter-var-root` or make the cache Var dynamic and use `set!`?
Whilst I agree that SoftCache is an anomaly, I'd note that TTLCache is immutable (maybe it was mutable back in 2014?) and that SoftCache, by its very nature, is built on top of mutable Java data structures – so it's always going to be the odd one out. I consider this to be a documentation issue – happy to see issues opened suggesting improvements to the README or the docs tree (or patches!).
Patch distinguishes between mutable and immutable caches, and classifies SoftCache and TTLCache as mutable.