Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the cl-cache-tables Reference Manual, version 0.0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Oct 13 09:23:52 2021 GMT+0.
| • Introduction | What cl-cache-tables is all about | |
| • Systems | The systems documentation | |
| • Files | The files documentation | |
| • Packages | The packages documentation | |
| • Definitions | The symbols documentation | |
| • Indexes | Concepts, functions, variables and data types |
cl-cache-tables is a small, portable, dependency-free library that facilitates caching of data such as lisp data structures.
It uses the native hash-tables of your lisp implementation under the hood, but implements an api that handles caching stuff such as key expiration, with little aditional overhead.
It works at least on sbcl, ecl, ccl, abcl and clisp.
This section assumes you use quicklisp. If you don't, you should! Download and learn about it here.
Once you have quicklisp loaded, simply do:
(ql:quickload :cl-cache-tables)
And it's all up and running. To run the tests do:
(ql:quickload :cl-cache-tables-tests)
Please report if any tests fail in your Common Lisp implementation.
> (ql:quickload :cl-cache-tables)
(:CL-CACHE-TABLES)
> (use-package :cache)
T
> (defvar *cache* (make-cache-table :test #'equal))
*cache*
> (progn
(cache-table-put "key" "value" *cache* :expire 1)
(print (cache-table-get "key" *cache*))
(sleep 1)
(print (cache-table-get "key" *cache*)))
"value"
nil
make-cache-table returns a newly created cache-table. The argument list is the same as in the native constuctor make-hash-table.
(defvar *cache* (make-cache-table :test #'equal))
cache-table-put populates the cache-table with a new key and value. The expire parameter is the time in seconds that the key will be present, where 0 means that it does not expire. Expire defaults to 0. cache-table-put returns the value that was set.
(cache-table-put "some-persistent-key" "persistent" *cache* :expire 0) ;; "persistent"
(cache-table-put "some-temporary-key" "temporary" *cache* :expire 10) ;; "temporary"
cache-table-get retrieves a value from key in cache-table. Returns two values, similarly to gethash: The first one is the value stored at key, and the second one is a generalized boolean indicating if the key exists (this allows us to distinguish the case where we store nil at a cache-table key).
(cache-table-get "some-persistent-key" *cache*)
"persistent"
T
Retrieves key from cache table, similarly to cache-table-get. When the key is not present (or has expired), fun is called with the key argument, to compute/retrieve it from another source. cache-table is then populated with the result and an expiration of "expire" seconds. Returns the value of key. Notice that when function returns nil, that value becomes cached as any other value, so if you want to signal that some value couldn't be found, your function should signal an error."
(defvar *cache* (make-hash-table :test #'equal)) ;; cache-table
(cache-table-get-or-fill "my-key" *cache* #'(lambda (key)
(retrieve-from-mongo key)) :expire 10)
"some-value" ;; retrieved from mongodb
(cache-table-get-or-fill "my-key" *cache* #'(lambda (key)
(retrieve-from-mongo key)) :expire 10)
"some-value" ;; retrieved from cache-table if less than 10 seconds elapsed, else retrieved from mongo.
cache-table-del deletes a key from the cache-table. Returns t if the key existed, nil otherwise.
(cache-table-del "some-non-existing-key" *cache*)
NIL
Similarly to maphash, receives a function of two arguments (key value), and applies it to every key-value pair in cache-table. Always returns nil.
(mapcache #'(lambda (key value) (print (cons key value))) *cache*)
("come-persistent-key" . "persistent")
("some-temporary-key" . "temporary")
NIL
cache-table-ttl returns the amount of time in seconds that a key still has before expiring. If the key is persistent, this function returns -1. If it does not exist, it returns nil.
(cache-table-ttl "some-temporary-key" *cache*)
8
(cache-table-ttl "some-persistent-key" *cache*)
-1
(cache-table-ttl "some-non-existing-key" *cache*)
NIL
cache-table-persist turns a temporary key to a persistent one, by removing the expiration. Returns T if key exists, NIL otherwise.
(cache-table-persist "some-temporary-key" *cache*)
T
(cache-table-ttl "a-non-existing-key" *cache*)
NIL
Returns the number of key-value pairs in a cache-table.
(cache-table-count *cache*)
345
clrcache removes all entries from cache-table and returns that empty cache-table.
(clrcache *cache*) ;; cash-table
(cache-table-count *cache*) ;; 0
copy-cache-table creates a new cache equal to cache-table and returns it.
(copy-cache-table *cache*) ;; new cache-table equal to cache-table
cache-table-p is a predicate that checks if cache-table if indeed a cache-table. Returns T if is, NIL otherwise.
(cache-table-p *cache*)
T
(cache-table-p 3)
NIL
If you have any suggestions, bug reports, etc, please fill in an issue describing it. If you have the time and want to contribute, that is even better! Submit some tests too, let's try and keep coverage up.
MIT
Next: Files, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
| • The cl-cache-tables system |
Diogo Franco
MIT
A wrapper around native hash-tables to facilitate
in-process caching of common lisp data structures.
0.0.1
cl-cache-tables.asd (file)
Files are sorted by type and then listed depth-first from the systems components trees.
| • Lisp files |
| • The cl-cache-tables.asd file | ||
| • The cl-cache-tables/package.lisp file | ||
| • The cl-cache-tables/cl-cache-tables.lisp file |
Next: The cl-cache-tables/package․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
cl-cache-tables.asd
cl-cache-tables (system)
Next: The cl-cache-tables/cl-cache-tables․lisp file, Previous: The cl-cache-tables․asd file, Up: Lisp files [Contents][Index]
cl-cache-tables (system)
package.lisp
Previous: The cl-cache-tables/package․lisp file, Up: Lisp files [Contents][Index]
package.lisp (file)
cl-cache-tables (system)
cl-cache-tables.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
| • The cache package |
package.lisp (file)
common-lisp
Definitions are sorted by export status, category, package, and then by lexicographic order.
| • Exported definitions | ||
| • Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
| • Exported functions |
Previous: Exported definitions, Up: Exported definitions [Contents][Index]
Returns the number of elements in cache-table. A cleared or new cache-table returns 0.
cl-cache-tables.lisp (file)
Deletes key from cache-table. Returns t if the key existed, nil otherwise.
cl-cache-tables.lisp (file)
Returns the value at key in cache-table. Also returns a second value that is T if the key exists, and nil if it doesn’t or has expired.
cl-cache-tables.lisp (file)
Retrieves key from cache table, similarly to cache-table-get.
When the key is not present, function is called with the key argument,
to compute/retrieve it from another source. cache-table is then populated
with the result and expiration of "expire" seconds. Returns the value
of key. Notice that when function returns nil, that value becomes cached as
any other value, so if you want to signal that some value couldn’t be found,
your function should throw an error
cl-cache-tables.lisp (file)
cl-cache-tables.lisp (file)
Removes the expiration from a key. Returns nil if key did not exist, and nil otherwise.
cl-cache-tables.lisp (file)
Sets key and value in cache-table. Expire is in seconds and defaults to 0, which means that this key will never expire. Returns value.
cl-cache-tables.lisp (file)
Returns the time to live (in seconds) of the key in cache-table.
If the key is persistent, returns -1. If it does not exist, returns nil.
cl-cache-tables.lisp (file)
Removes all entries from cache-table and returns that empty cache-table.
cl-cache-tables.lisp (file)
Creates a new cache-table equal to cache-table and returns it.
cl-cache-tables.lisp (file)
cl-cache-tables.lisp (file)
Calls fun for every existing and non-expired key value pair in cache-table. Similarly to maphash, returns nil.
cl-cache-tables.lisp (file)
Previous: Exported definitions, Up: Definitions [Contents][Index]
| • Internal functions | ||
| • Internal structures |
Next: Internal structures, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
cl-cache-tables.lisp (file)
cl-cache-tables.lisp (file)
cl-cache-tables.lisp (file)
cl-cache-tables.lisp (file)
cl-cache-tables.lisp (file)
Helper function that copies a hash table.
cl-cache-tables.lisp (file)
Previous: Internal functions, Up: Internal definitions [Contents][Index]
cl-cache-tables.lisp (file)
structure-object (structure)
cache-table-test (function)
(setf cache-table-test) (function)
cache-table-size (function)
(setf cache-table-size) (function)
cache-table-rehash-size (function)
(setf cache-table-rehash-size) (function)
cache-table-rehash-threshold (function)
(setf cache-table-rehash-threshold) (function)
cache-table-hash (function)
(setf cache-table-hash) (function)
Previous: Definitions, Up: Top [Contents][Index]
| • Concept index | ||
| • Function index | ||
| • Variable index | ||
| • Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
| Jump to: | C F L |
|---|
| Jump to: | C F L |
|---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
| Jump to: | (
C F M |
|---|
| Jump to: | (
C F M |
|---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
| Jump to: | H R S T |
|---|
| Jump to: | H R S T |
|---|
Previous: Variable index, Up: Indexes [Contents][Index]
| Jump to: | C P S |
|---|
| Jump to: | C P S |
|---|