sema-cache 0.1.0

TTL and LRU caching, memoization, and optional persistent kv-backed caches

API reference 10 exports

Exported declarations from this release. Parameter names and descriptions come directly from its source.

cache/clear!

Source :170
(cache/clear! c)
Remove every entry. The :hits/:misses/:evictions counters are preserved; :size drops to 0. Returns nil.
View source definition
(define (cache/clear! c)
  "Remove every entry. The :hits/:misses/:evictions counters are preserved;
:size drops to 0. Returns nil."
  (c :clear!))

cache/contains?

Source :159
(cache/contains? c k)
Return #t if k has a live (non-expired) entry, #f otherwise. Does not touch LRU recency and does not count toward :hits/:misses.
View source definition
(define (cache/contains? c k)
  "Return #t if k has a live (non-expired) entry, #f otherwise.
Does not touch LRU recency and does not count toward :hits/:misses."
  (c :contains? k))

cache/evict!

Source :164
(cache/evict! c k)
Remove k from the cache. Returns #t if it was present, #f otherwise. Manual eviction does not count toward the :evictions stat (which tracks capacity- and TTL-driven evictions only).
View source definition
(define (cache/evict! c k)
  "Remove k from the cache. Returns #t if it was present, #f otherwise.
Manual eviction does not count toward the :evictions stat (which tracks
capacity- and TTL-driven evictions only)."
  (c :evict! k))

cache/get

Source :131
(cache/get c k . default)
Return the cached value for k, or default (nil) on a miss. A hit counts toward :hits and refreshes LRU recency; a miss — including an expired entry — counts toward :misses. nil values are cacheable, so a nil return is ambiguous: use cache/contains? or a sentinel default to distinguish.
View source definition
(define (cache/get c k . default)
  "Return the cached value for k, or default (nil) on a miss.
A hit counts toward :hits and refreshes LRU recency; a miss — including an
expired entry — counts toward :misses. nil values are cacheable, so a nil
return is ambiguous: use cache/contains? or a sentinel default to distinguish."
  (let ((entry (c :lookup! k)))
    (if (nil? entry)
        (if (null? default) nil (first default))
        (get entry :value))))

cache/get-or

Source :141
(cache/get-or c k thunk)
Return the cached value for k, or run thunk, cache its result, and return it. A hit refreshes LRU recency and never calls thunk — a cached nil is a hit too (stored entries are distinguished from misses internally, not by value). A miss runs thunk exactly once and stores the result, evicting if full.
View source definition
(define (cache/get-or c k thunk)
  "Return the cached value for k, or run thunk, cache its result, and return it.
A hit refreshes LRU recency and never calls thunk — a cached nil is a hit too
(stored entries are distinguished from misses internally, not by value).
A miss runs thunk exactly once and stores the result, evicting if full."
  (let ((entry (c :lookup! k)))
    (if (nil? entry)
        (let ((v (thunk)))
          (c :put! k v)
          v)
        (get entry :value))))

cache/kv-cache

Source :206
(cache/kv-cache name path . opts)
Open a persistent cache backed by the stdlib kv store (a JSON file at path). name is the process-local kv handle; entries survive across runs in the file. Keys must be strings. Values must round-trip through JSON: keywords become strings, string map keys come back as keywords, NaN/Infinity floats become nil — cache only JSON-representable data. Options: :ttl-ms (nil = no expiry), :clock-fn (for testing; defaults to time-ms). There is no :max-size/:policy — the kv file has no recency index and every write rewrites the whole file, so capacity eviction belongs in an in-memory cache/new, not here. Returns a handle usable with every cache/* function; the :hits/:misses/:evictions counters are per-process and reset on each open.
View source definition
(define (cache/kv-cache name path . opts)
  "Open a persistent cache backed by the stdlib kv store (a JSON file at path).
name is the process-local kv handle; entries survive across runs in the file.
Keys must be strings. Values must round-trip through JSON: keywords become
strings, string map keys come back as keywords, NaN/Infinity floats become
nil — cache only JSON-representable data. Options: :ttl-ms (nil = no expiry),
:clock-fn (for testing; defaults to time-ms). There is no :max-size/:policy —
the kv file has no recency index and every write rewrites the whole file, so
capacity eviction belongs in an in-memory cache/new, not here. Returns a
handle usable with every cache/* function; the :hits/:misses/:evictions
counters are per-process and reset on each open."
  (let* ((o         (if (null? opts) {} (first opts)))
         (ttl-ms    (get o :ttl-ms nil))
         (clock-fn  (get o :clock-fn time-ms))
         (hits      0)
         (misses    0)
         (evictions 0))
    (kv/open name path)
    (define (expired? row)
      (entry-expired? row ttl-ms clock-fn))
    (define (lookup! k)
      (let ((row (kv/get name (kv-key! k))))
        (cond
          ((nil? row)
           (set! misses (+ misses 1))
           nil)
          ((expired? row)
           (kv/delete name k)
           (set! evictions (+ evictions 1))
           (set! misses (+ misses 1))
           nil)
          (else
           (set! hits (+ hits 1))
           row))))
    (fn (msg . args)
      (cond
        ((= msg :lookup!) (lookup! (first args)))
        ((= msg :contains?)
         (let ((row (kv/get name (kv-key! (first args)))))
           (and (not (nil? row)) (not (expired? row)))))
        ((= msg :put!)
         (kv/set name (kv-key! (first args))
                 {:value (nth args 1) :written (clock-fn)})
         nil)
        ((= msg :evict!) (kv/delete name (kv-key! (first args))))
        ((= msg :clear!)
         (for-each (fn (k) (kv/delete name k)) (kv/keys name))
         nil)
        ((= msg :stats)
         {:hits hits :misses misses :evictions evictions
          :size (length (kv/keys name))})
        (else
         (error (format "sema-cache: unknown message ~a" msg))))))))

cache/memoize

Source :183
(cache/memoize f . opts)
Return a memoized version of f backed by an internal cache/new. The cache key is the full argument list (equal?-based), so multi-arg and variadic functions work; (m 1 2) and (m 2 1) are distinct keys. Accepts the same options map as cache/new, plus :cache — a pre-built handle to use instead, which lets you inspect cache/stats or evict entries from outside.
View source definition
(define (cache/memoize f . opts)
  "Return a memoized version of f backed by an internal cache/new.
The cache key is the full argument list (equal?-based), so multi-arg and
variadic functions work; (m 1 2) and (m 2 1) are distinct keys. Accepts the
same options map as cache/new, plus :cache — a pre-built handle to use
instead, which lets you inspect cache/stats or evict entries from outside."
  (let* ((o (if (null? opts) {} (first opts)))
         (c (get o :cache (cache/new (dissoc o :cache)))))
    (fn ( . args)
      (cache/get-or c args (fn () (apply f args))))))

cache/new

Source :52
(cache/new . opts)
Create an in-memory cache handle. Options: :max-size (1024) entries before eviction, :ttl-ms (nil = no expiry) milliseconds after write before an entry expires, :policy :lru (default, evicts the least-recently-used entry) or :fifo (evicts the oldest insertion; re-putting a key counts as re-insertion), :clock-fn (for testing; defaults to time-ms). Expired entries are evicted lazily on access and never count as hits. Keys are compared with equal?, so lists, strings, and maps all work as keys.
View source definition
(define (cache/new . opts)
  "Create an in-memory cache handle.
Options: :max-size (1024) entries before eviction, :ttl-ms (nil = no expiry)
milliseconds after write before an entry expires, :policy :lru (default,
evicts the least-recently-used entry) or :fifo (evicts the oldest insertion;
re-putting a key counts as re-insertion), :clock-fn (for testing; defaults to
time-ms). Expired entries are evicted lazily on access and never count as hits.
Keys are compared with equal?, so lists, strings, and maps all work as keys."
  (let* ((o         (if (null? opts) {} (first opts)))
         (max-size  (get o :max-size 1024))
         (ttl-ms    (get o :ttl-ms nil))
         (policy    (get o :policy :lru))
         (clock-fn  (get o :clock-fn time-ms))
         (entries   {})
         (counter   0)
         (hits      0)
         (misses    0)
         (evictions 0))
    (when (not (or (= policy :lru) (= policy :fifo)))
      (error (format "cache/new: unknown :policy ~a — use :lru or :fifo" policy)))
    (when (< max-size 1)
      (error (format "cache/new: :max-size must be at least 1 — got ~a" max-size)))
    (define (expired? entry)
      (entry-expired? entry ttl-ms clock-fn))
    ;; Touching lookup: returns the entry map, or nil on miss/expiry.
    ;; The entry map is never nil, so a stored nil value is still a hit.
    (define (lookup! k)
      (let ((entry (get entries k)))
        (cond
          ((nil? entry)
           (set! misses (+ misses 1))
           nil)
          ((expired? entry)
           (set! entries (dissoc entries k))
           (set! evictions (+ evictions 1))
           (set! misses (+ misses 1))
           nil)
          (else
           (set! counter (+ counter 1))
           (set! entries (assoc entries k (assoc entry :touched counter)))
           (set! hits (+ hits 1))
           entry))))
    (define (store! k v)
      (when (and (not (contains? entries k))
                 (>= (count entries) max-size))
        (let ((slot (if (= policy :lru) :touched :inserted)))
          (set! entries (dissoc entries (victim-key entries slot)))
          (set! evictions (+ evictions 1))))
      (set! counter (+ counter 1))
      (set! entries (assoc entries k {:value v
                                      :written (clock-fn)
                                      :touched counter
                                      :inserted counter}))
      nil)
    (fn (msg . args)
      (cond
        ((= msg :lookup!) (lookup! (first args)))
        ((= msg :contains?)
         ;; Non-touching and non-counting: answers expiry-aware presence
         ;; without bumping recency or the hit/miss counters.
         (let ((entry (get entries (first args))))
           (and (not (nil? entry)) (not (expired? entry)))))
        ((= msg :put!) (store! (first args) (nth args 1)))
        ((= msg :evict!)
         (if (contains? entries (first args))
             (begin (set! entries (dissoc entries (first args))) #t)
             #f))
        ((= msg :clear!)
         (set! entries {})
         nil)
        ((= msg :stats)
         {:hits hits :misses misses :evictions evictions :size (count entries)})
        (else
         (error (format "sema-cache: unknown message ~a" msg)))))))

cache/put!

Source :153
(cache/put! c k v)
Store v under k, evicting per the cache's policy if it is full. Overwriting an existing key never evicts; it refreshes the entry's TTL clock, LRU recency, and (for :fifo) its insertion order. Returns nil.
View source definition
(define (cache/put! c k v)
  "Store v under k, evicting per the cache's policy if it is full.
Overwriting an existing key never evicts; it refreshes the entry's TTL clock,
LRU recency, and (for :fifo) its insertion order. Returns nil."
  (c :put! k v))

cache/stats

Source :175
(cache/stats c)
Return {:hits n :misses n :evictions n :size n} for the cache.
View source definition
(define (cache/stats c)
  "Return {:hits n :misses n :evictions n :size n} for the cache."
  (c :stats))
About this reference

Generated with sema-reader 1.37.0 without executing package code. These are source declarations; dynamic exports, aliases, and runtime changes are not inferred.

Archive SHA-256 a076dcd4ef3dc8ab48fbafcb5c0c38bb2d3f7159b585faf562b9b9507bdc4d01