The cl-cache-tables Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-cache-tables Reference Manual

This is the cl-cache-tables Reference Manual, version 0.0.1, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 03:09:52 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

cl-cache-tables

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.

How do i use it?

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.

Example

> (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

API

(make-cache-table &key (test #'eql) (size 1024) (rehash-size 1.5) (rehash-threshold 0.75))

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 key value cache-table &key (expire 0))

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 key cache-table)

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

(cache-table-get-or-fill key cache-table fun &key (expire 0))

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 key cache-table)

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

(mapcache function cache-table)

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 key cache-table)

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 key cache-table)

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

(cache-table-count cache-table)

Returns the number of key-value pairs in a cache-table.

(cache-table-count *cache*)
345

(clrcache cache-table)

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 cache-table)

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 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

Contributing

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.

License

MIT


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 cl-cache-tables

Author

Diogo Franco

License

MIT

Description

A wrapper around native hash-tables to facilitate
in-process caching of common lisp data structures.

Version

0.0.1

Source

cl-cache-tables.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 cl-cache-tables.asd

Location

cl-cache-tables.asd

Systems

cl-cache-tables (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 cl-cache-tables/package.lisp

Parent

cl-cache-tables (system)

Location

package.lisp

Packages

cache


Previous: , Up: Lisp files   [Contents][Index]

3.1.3 cl-cache-tables/cl-cache-tables.lisp

Dependency

package.lisp (file)

Parent

cl-cache-tables (system)

Location

cl-cache-tables.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 cache

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Functions

Function: cache-table-count CACHE-TABLE

Returns the number of elements in cache-table. A cleared or new cache-table returns 0.

Package

cache

Source

cl-cache-tables.lisp (file)

Function: cache-table-del KEY CACHE-TABLE

Deletes key from cache-table. Returns t if the key existed, nil otherwise.

Package

cache

Source

cl-cache-tables.lisp (file)

Function: cache-table-get KEY CACHE-TABLE

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.

Package

cache

Source

cl-cache-tables.lisp (file)

Function: cache-table-get-or-fill KEY CACHE-TABLE FUN &key EXPIRE

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

Package

cache

Source

cl-cache-tables.lisp (file)

Function: cache-table-p OBJECT
Package

cache

Source

cl-cache-tables.lisp (file)

Function: cache-table-persist KEY CACHE-TABLE

Removes the expiration from a key. Returns nil if key did not exist, and nil otherwise.

Package

cache

Source

cl-cache-tables.lisp (file)

Function: cache-table-put KEY VALUE CACHE-TABLE &key EXPIRE

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.

Package

cache

Source

cl-cache-tables.lisp (file)

Function: cache-table-ttl KEY CACHE-TABLE

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.

Package

cache

Source

cl-cache-tables.lisp (file)

Function: clrcache CACHE-TABLE

Removes all entries from cache-table and returns that empty cache-table.

Package

cache

Source

cl-cache-tables.lisp (file)

Function: copy-cache-table CACHE-TABLE

Creates a new cache-table equal to cache-table and returns it.

Package

cache

Source

cl-cache-tables.lisp (file)

Function: make-cache-table &key TEST REHASH-SIZE REHASH-THRESHOLD SIZE &aux HASH
Package

cache

Source

cl-cache-tables.lisp (file)

Function: mapcache FUNCTION CACHE-TABLE

Calls fun for every existing and non-expired key value pair in cache-table. Similarly to maphash, returns nil.

Package

cache

Source

cl-cache-tables.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Functions

Function: cache-table-hash INSTANCE
Function: (setf cache-table-hash) VALUE INSTANCE
Package

cache

Source

cl-cache-tables.lisp (file)

Function: cache-table-rehash-size INSTANCE
Function: (setf cache-table-rehash-size) VALUE INSTANCE
Package

cache

Source

cl-cache-tables.lisp (file)

Function: cache-table-rehash-threshold INSTANCE
Function: (setf cache-table-rehash-threshold) VALUE INSTANCE
Package

cache

Source

cl-cache-tables.lisp (file)

Function: cache-table-size INSTANCE
Function: (setf cache-table-size) VALUE INSTANCE
Package

cache

Source

cl-cache-tables.lisp (file)

Function: cache-table-test INSTANCE
Function: (setf cache-table-test) VALUE INSTANCE
Package

cache

Source

cl-cache-tables.lisp (file)

Function: copy-hash-table HASH-TABLE

Helper function that copies a hash table.

Package

cache

Source

cl-cache-tables.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Structures

Structure: cache-table ()
Package

cache

Source

cl-cache-tables.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots
Slot: test
Readers

cache-table-test (function)

Writers

(setf cache-table-test) (function)

Slot: size
Readers

cache-table-size (function)

Writers

(setf cache-table-size) (function)

Slot: rehash-size
Readers

cache-table-rehash-size (function)

Writers

(setf cache-table-rehash-size) (function)

Slot: rehash-threshold
Readers

cache-table-rehash-threshold (function)

Writers

(setf cache-table-rehash-threshold) (function)

Slot: hash
Readers

cache-table-hash (function)

Writers

(setf cache-table-hash) (function)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
cl-cache-tables.asd: The cl-cache-tables<dot>asd file
cl-cache-tables/cl-cache-tables.lisp: The cl-cache-tables/cl-cache-tables<dot>lisp file
cl-cache-tables/package.lisp: The cl-cache-tables/package<dot>lisp file

F
File, Lisp, cl-cache-tables.asd: The cl-cache-tables<dot>asd file
File, Lisp, cl-cache-tables/cl-cache-tables.lisp: The cl-cache-tables/cl-cache-tables<dot>lisp file
File, Lisp, cl-cache-tables/package.lisp: The cl-cache-tables/package<dot>lisp file

L
Lisp File, cl-cache-tables.asd: The cl-cache-tables<dot>asd file
Lisp File, cl-cache-tables/cl-cache-tables.lisp: The cl-cache-tables/cl-cache-tables<dot>lisp file
Lisp File, cl-cache-tables/package.lisp: The cl-cache-tables/package<dot>lisp file

Jump to:   C   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   (  
C   F   M  
Index Entry  Section

(
(setf cache-table-hash): Internal functions
(setf cache-table-rehash-size): Internal functions
(setf cache-table-rehash-threshold): Internal functions
(setf cache-table-size): Internal functions
(setf cache-table-test): Internal functions

C
cache-table-count: Exported functions
cache-table-del: Exported functions
cache-table-get: Exported functions
cache-table-get-or-fill: Exported functions
cache-table-hash: Internal functions
cache-table-p: Exported functions
cache-table-persist: Exported functions
cache-table-put: Exported functions
cache-table-rehash-size: Internal functions
cache-table-rehash-threshold: Internal functions
cache-table-size: Internal functions
cache-table-test: Internal functions
cache-table-ttl: Exported functions
clrcache: Exported functions
copy-cache-table: Exported functions
copy-hash-table: Internal functions

F
Function, (setf cache-table-hash): Internal functions
Function, (setf cache-table-rehash-size): Internal functions
Function, (setf cache-table-rehash-threshold): Internal functions
Function, (setf cache-table-size): Internal functions
Function, (setf cache-table-test): Internal functions
Function, cache-table-count: Exported functions
Function, cache-table-del: Exported functions
Function, cache-table-get: Exported functions
Function, cache-table-get-or-fill: Exported functions
Function, cache-table-hash: Internal functions
Function, cache-table-p: Exported functions
Function, cache-table-persist: Exported functions
Function, cache-table-put: Exported functions
Function, cache-table-rehash-size: Internal functions
Function, cache-table-rehash-threshold: Internal functions
Function, cache-table-size: Internal functions
Function, cache-table-test: Internal functions
Function, cache-table-ttl: Exported functions
Function, clrcache: Exported functions
Function, copy-cache-table: Exported functions
Function, copy-hash-table: Internal functions
Function, make-cache-table: Exported functions
Function, mapcache: Exported functions

M
make-cache-table: Exported functions
mapcache: Exported functions

Jump to:   (  
C   F   M  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   H   R   S   T  
Index Entry  Section

H
hash: Internal structures

R
rehash-size: Internal structures
rehash-threshold: Internal structures

S
size: Internal structures
Slot, hash: Internal structures
Slot, rehash-size: Internal structures
Slot, rehash-threshold: Internal structures
Slot, size: Internal structures
Slot, test: Internal structures

T
test: Internal structures

Jump to:   H   R   S   T  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   P   S  
Index Entry  Section

C
cache: The cache package
cache-table: Internal structures
cl-cache-tables: The cl-cache-tables system

P
Package, cache: The cache package

S
Structure, cache-table: Internal structures
System, cl-cache-tables: The cl-cache-tables system

Jump to:   C   P   S