The clache Reference Manual

Table of Contents

The clache Reference Manual

This is the clache Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Oct 13 10:21:19 2021 GMT+0.

1 Introduction

CLACHE

CLACHE is a general caching library for Common Lisp.

Overview

CLACHE provides a general caching facility for Common Lisp. The API is similar with standard hash-table interface. Let me show you an overview of API.

• getcache - Get cache from storage
• setcache - Store cache into storage
• remcache - Remove cache from storage
• clrcache - Clear all cache in storage

As you can see, it is easy to use. Here is an example:

;; Create a store
(defparamater *store* (progn
                         (ensure-directories-exist #p"cache/")
                         (make-instance 'file-store :directory #p"cache/")))

;; Store cache
(setcache 1 "foo" *store*)
;;=> 1

;; Get cache
(getcache 1 *store*)
;;=> 1, T

;; Get non-exited cache
(getcache 42 *store*)
;;=> NIL, NIL

;; Remove cache
(remcache 1 *store*)
;;=> T

;; Clear all cache
(clrcache *store*)

API

Caches

A cache is a triple of a key, a value, and an expiration time.

Cache Keys

Any object can be used as a cache key if the object can be converted into a string properly by using cache-key-to-string.

Cache Values

Same as cache keys, any object can be used as a cache value. However, a type of cache values can be limited by storages. So you have to be careful what storage are you using.

Expiration Time

An expiration time describes how long caches live in seconds. If an expiration time is nil, such caches will never be expired: persistent cache.

Cache Existence

If a cache is stored in a storage and has not yet been expired or a persitent cache, we express the cache exists in the storage.

Storages

Storage is an abstract layer of maintaining caches. You can access storages via API.

Default Storage

Function: getcache

getcache key storage

Retrieve a cache value from storage indicated by key and return values of the cache value and a boolean whether the cache exists in storage. The cache value will be nil if such the cache doesn't exist. For example, (getcache "not-existed-cache") will return nil, nil.

Function: setcache

setcache key value storage &optional expire

Store a cache value into storage with key and expire. expire is an expiration time in seconds. If expire is nil, the cache will never be expired. The return value is value that has been stored.

Function: (setf getcache)

(setf getcache) value key storage &optional expire 

Same as setcache.

Function: remcache

remcache key storage

Remove a cache from storage indicated by key. If the cache has been successfully removed, this function returns t, otherwise returns nil.

Function: clrcache

clrcache storage

Remove all caches from storage. The return value is undefined.

Macro: with-cache

Annotation: cache

Protocol

Supported Implementations

• Allegro CL v8.2
• SBCL v1.0.47
• CMU CL v20b
• Clozure CL v1.6
• ECL v11.1.1
• GNU CLISP v2.48

Copyright (C) 2011 Tomohiro Matsuyama <tomo@cx4a.org>

2 Systems

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

2.1 clache

Maintainer

Olexiy Zamkoviy

Author

Tomohiro Matsuyama

License

LLGPL

Dependencies

• alexandria
• trivial-garbage
• babel
• ironclad
• cl-fad
• cl-store
• cl-annot
• cl-syntax
• cl-syntax-annot

Source

clache.asd (file)

Component

src (module)

3 Modules

Modules are listed depth-first from the system components tree.

3.1 clache/src

Parent

clache (system)

Location

src/

Components

• package.lisp (file)
• utils.lisp (file)
• protocol.lisp (file)
• stores (module)
• api.lisp (file)

3.2 clache/src/stores

Dependency

protocol.lisp (file)

Parent

src (module)

Location

src/stores/

Components

• memory.lisp (file)
• file.lisp (file)

4 Files

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

4.1 Lisp

4.1.1 clache.asd

Location

clache.asd

Systems

clache (system)

Packages

clache-asd

4.1.2 clache/src/package.lisp

Parent

src (module)

Location

src/package.lisp

Packages

clache

4.1.3 clache/src/utils.lisp

Dependency

package.lisp (file)

Parent

src (module)

Location

src/utils.lisp

Internal Definitions

• md5-hex-string (function)
• object-to-string (function)
• symbol-fqn (function)

4.1.4 clache/src/protocol.lisp

Dependency

utils.lisp (file)

Parent

src (module)

Location

src/protocol.lisp

Exported Definitions

• cache-key-to-string (generic function)
• cache-key-to-string (method)
• clear-cache (generic function)
• delete-cache (generic function)
• load-cache (generic function)
• never-expire-p (function)
• store (class)
• store-cache (generic function)

Internal Definitions

expire (type)

4.1.5 clache/src/stores/memory.lisp

Parent

stores (module)

Location

src/stores/memory.lisp

Exported Definitions

• clear-cache (method)
• delete-cache (method)
• load-cache (method)
• memory-store (class)
• store-cache (method)

Internal Definitions

hash-table-of (method)

4.1.6 clache/src/stores/file.lisp

Dependency

memory.lisp (file)

Parent

stores (module)

Location

src/stores/file.lisp

Exported Definitions

• clear-cache (method)
• delete-cache (method)
• file-store (class)
• load-cache (method)
• store-cache (method)

Internal Definitions

• cache-path (function)
• directory-of (method)

4.1.7 clache/src/api.lisp

Dependency

stores (module)

Parent

src (module)

Location

src/api.lisp

Exported Definitions

• cache (macro)
• clrcache (function)
• getcache (function)
• (setf getcache) (function)
• remcache (function)
• setcache (function)
• with-cache (macro)
• with-inline-cache (macro)

5 Packages

Packages are listed by definition order.

5.1 clache-asd

Source

clache.asd

Use List

• asdf/interface
• common-lisp

5.2 clache

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions

• cache (macro)
• cache-key-to-string (generic function)
• cache-key-to-string (method)
• clear-cache (generic function)
• clear-cache (method)
• clear-cache (method)
• clrcache (function)
• delete-cache (generic function)
• delete-cache (method)
• delete-cache (method)
• file-store (class)
• getcache (function)
• (setf getcache) (function)
• load-cache (generic function)
• load-cache (method)
• load-cache (method)
• memory-store (class)
• never-expire-p (function)
• remcache (function)
• setcache (function)
• store (class)
• store-cache (generic function)
• store-cache (method)
• store-cache (method)
• with-cache (macro)
• with-inline-cache (macro)

Internal Definitions

• cache-path (function)
• directory-of (generic function)
• directory-of (method)
• expire (type)
• hash-table-of (generic function)
• hash-table-of (method)
• md5-hex-string (function)
• object-to-string (function)
• symbol-fqn (function)

6 Definitions

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

6.1 Exported definitions

6.1.1 Macros

Macro: cache (KEYARGS &key STORE EXPIRE) FUNCTION-DEFINITION-FORM

Annotation for caching functions with their arguments. This should be used with CL-ANNOT. KEYARGS is a form or a list of form for making a cache key. To make cache keys distinct as to the function, you may add a keyword or a symbol into KEYARGS. See also WITH-CACHE.

Example:

@cache ((:f x y z))
(defun f (x y z)
...)

;; Remove a cache of F
(remcache ’(:f 1 2 3))

Package

clache

Source

api.lisp (file)

Macro: with-cache (KEY &key STORE EXPIRE) &body BODY

If a cache indicated by KEY exists, this just returns the cache value without evaluating BODY. Otherwise, this evaluates BODY and stores the evaluated value into STORE with KEY and EXPIRE. KEY is a form that an evaluated value indicates the cache key.

Example:

(defun f (x)
(with-cache (x *store*)
(very-complex-computation x)))

Package

clache

Source

api.lisp (file)

Macro: with-inline-cache (KEY &key EXPIRE TEST WEAKNESS) &body BODY

Same as WITH-CACHE, except that an inline memory store will be used as a cache store. TEST is a function to test hash table keys of the memory store. WEAKNESS specifies the hash table is weak-hash-table or not.

Package

clache

Source

api.lisp (file)

6.1.2 Functions

Function: clrcache STORE

Remove all caches from STORE. The return value is undefined.

Package

clache

Source

api.lisp (file)

Function: getcache KEY STORE

Retrieve a cache value from STORE indicated by KEY and return values of the cache value and a boolean whether the cache exists in STORE. The cache value will be NIL if such the cache doesn’t exist. For example, (getcache "not-existed-cache") will return NIL, NIL.

Package

clache

Source

api.lisp (file)

Writer

(setf getcache) (function)

Function: (setf getcache) VALUE KEY STORE &key EXPIRE

Package

clache

Source

api.lisp (file)

Reader

getcache (function)

Function: never-expire-p EXPIRE

Return T if EXPIRE represents caches will never be expired.

Package

clache

Source

protocol.lisp (file)

Function: remcache KEY STORE

Remove a cache from STORE indicated by KEY. If the cache has been successfully removed, this function returns T, otherwise returns NIL.

Package

clache

Source

api.lisp (file)

Function: setcache KEY VALUE STORE &key EXPIRE

Store a cache VALUE into STORE with KEY and EXPIRE. EXPIRE is an expiration time in seconds. If EXPIRE is NIL, the cache will never be expired. The return value is VALUE that has been stored.

Package

clache

Source

api.lisp (file)

6.1.3 Generic functions

Generic Function: cache-key-to-string KEY

This function converts any type of KEY into
string. This should be an injective function, meaning this should not lose the information about key.

Package

clache

Source

protocol.lisp (file)

Methods

Method: cache-key-to-string KEY

Generic Function: clear-cache STORE

Remove all caches from STORE. Any object can be returned.

Package

clache

Source

protocol.lisp (file)

Methods

Method: clear-cache (STORE file-store)

Source

file.lisp (file)

Method: clear-cache (STORE memory-store)

Source

memory.lisp (file)

Generic Function: delete-cache KEY STORE

Remove a cache indicated by KEY from STORE. If the
cache has been successfully removed, this function should return T, otherwise should return NIL.

Package

clache

Source

protocol.lisp (file)

Methods

Method: delete-cache KEY (STORE file-store)

Source

file.lisp (file)

Method: delete-cache KEY (STORE memory-store)

Source

memory.lisp (file)

Generic Function: load-cache KEY STORE

Try to retrieve a cache indicated by KEY from STORE
and return values of the cache value and a boolean whether the cache exists in STORE. The cache value should be NIL if such the cache doesn’t exist or has been expired.

Package

clache

Source

protocol.lisp (file)

Methods

Method: load-cache KEY (STORE file-store)

Source

file.lisp (file)

Method: load-cache KEY (STORE memory-store)

Source

memory.lisp (file)

Generic Function: store-cache KEY VALUE STORE EXPIRE

Store a cache VALUE with KEY into STORE. EXPIRE is
a keep time in seconds. If EXPIRE is NIL, the cache will never expired. This function should return the value that has been stored.

Package

clache

Source

protocol.lisp (file)

Methods

Method: store-cache KEY VALUE (STORE file-store) EXPIRE

Source

file.lisp (file)

Method: store-cache KEY VALUE (STORE memory-store) EXPIRE

Source

memory.lisp (file)

6.1.4 Classes

Class: file-store ()

Package

clache

Source

file.lisp (file)

Direct superclasses

store (class)

Direct methods

• clear-cache (method)
• delete-cache (method)
• store-cache (method)
• load-cache (method)
• directory-of (method)

Direct slots

Slot: directory

Initargs

:directory

Initform

(cl-annot.slot::required-argument :directory)

Readers

directory-of (generic function)

Class: memory-store ()

Package

clache

Source

memory.lisp (file)

Direct superclasses

store (class)

Direct methods

• clear-cache (method)
• delete-cache (method)
• store-cache (method)
• load-cache (method)
• hash-table-of (method)

Direct slots

Slot: hash-table

Initargs

:hash-table

Initform

(make-hash-table :test (function equal))

Readers

hash-table-of (generic function)

Class: store ()

An abstract class of stores. All stores must inherit from this class.

Package

clache

Source

protocol.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

• memory-store (class)
• file-store (class)

6.2 Internal definitions

6.2.1 Functions

Function: cache-path KEY STORE

Package

clache

Source

file.lisp (file)

Function: md5-hex-string STRING

Return a MD5 digest of STRING in hex string.

Package

clache

Source

utils.lisp (file)

Function: object-to-string OBJECT

Convert OBJECT into string by using PRINC-TO-STRING if OBJECT is not a symbol, or by using SYMBOL-FQN if OBJECT is a symbol.

Package

clache

Source

utils.lisp (file)

Function: symbol-fqn SYMBOL

Return a fully qualified name of SYMBOL in string. For example, (symbol-fqn ’if) will return "COMMON-LISP:IF".

Package

clache

Source

utils.lisp (file)

6.2.2 Generic functions

Generic Function: directory-of OBJECT

Package

clache

Methods

Method: directory-of (FILE-STORE file-store)

automatically generated reader method

Source

file.lisp (file)

Generic Function: hash-table-of OBJECT

Package

clache

Methods

Method: hash-table-of (MEMORY-STORE memory-store)

automatically generated reader method

Source

memory.lisp (file)

6.2.3 Types

Type: expire ()

Type for expiration time.

Package

clache

Source

protocol.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types