On this page:
make-cache
make-cacheeq
cache?
cache-eq?
cache-ref
cache-set!
cache-clear!

3 Write-through cache

 (require (planet untyped/unlib/cache))
A write-through cache is essentially a hash table that calls user supplied functions to load and store data from a back-end store (a database, file, network resource or other). This is useful for, for example, caching database values so that writes are always sent to the database (so it is always up-to-date) but data is only loaded as needed.
The cache associates a fixed life-span to all stored data, so data in the cache will eventually be removed. This ensures data is the cache does not get too old, and additionally that memory consumption is constrained.

(make-cache load-proc    
  store-proc    
  [#:expire expire-proc    
  #:lifetime lifetime])  cache?
  load-proc : (-> key value)
  store-proc : (-> key value void?)
  expire-proc : (-> cache? key value void?) = void
  lifetime : natural? = 3600
Creates a write-through cache using the given load-proc and store-proc and equal? has a key comparison function.

load-proc is called by cache-ref when there is no cached value for a given key. It is passed the key and must return the corresponding value from the back-end store. cache-ref updates the cache with the loaded value: subsequent requests for the same key will not trigger load-proc until the cached value expires.
store-proc is called by cache-set!. It is passed a key and value and must update the back-end store. cache-set! updates the cache automatically.
The optional expire-proc is called immediately after a value is removed from the cache (either manually or through natural expiry). The function is passed a reference to the cache, the key and the expiring value. The default function does nothing but user-supplied functions can, for example, add the data back to the cache or re-query the back-end store.
The optional lifetime specifies the number of seconds that each item is stored in the cache.
Items are expired in two ways:
  • a thread makes sweeps of the entire cache once every (/ lifetime 2) seconds;

  • cache-ref checks if a requested key has expired since the most recent sweep.

(make-cacheeq load-proc    
  store-proc    
  [#:expire expire-proc    
  #:lifetime lifetime])  cache?
  load-proc : (-> key value)
  store-proc : (-> key value void?)
  expire-proc : (-> cache? key value void?) = void
  lifetime : natural? = 3600
Like make-cache but uses eq? as the key comparison function.

(cache? item)  boolean?
  item : any
Predicate for identifying caches. Returns #t for caches created with make-cache and make-cacheeq.

(cache-eq? cache)  boolean?
  cache : cache?
Returns #t if cache uses eq? as its key comparison function (i.e. it was created with make-cacheeq rather than make-cache).

(cache-ref cache key)  value
  cache : cache?
  key : key
Retrieves a value from cache. If the cache contains a value for key, the value is returned immediately. If the cache does not contain a value for key (or the value has recently expired; see make-cache for more information), its load-proc is called to retrieve the value from its back-end store.

(cache-set! cache key value)  void?
  cache : cache?
  key : key
  value : value
Stores the supplied key/value pair in cache and calls its store-proc to update its back-end store.

(cache-clear! cache key)  void?
  cache : cache?
  key : key
Removes all values from cache, calling its expire-proc for each value.