The clache Reference Manual

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

The clache Reference Manual

This is the clache Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Thu Sep 15 04:19:53 2022 GMT+0.

Table of Contents


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.

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


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


2 Systems

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


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

2.1 clache

Maintainer

Olexiy Zamkoviy

Author

Tomohiro Matsuyama

License

LLGPL

Dependencies
  • alexandria (system).
  • trivial-garbage (system).
  • babel (system).
  • ironclad (system).
  • cl-fad (system).
  • cl-store (system).
  • cl-annot (system).
  • cl-syntax (system).
  • cl-syntax-annot (system).
Source

clache.asd.

Child Component

src (module).


3 Modules

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


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

3.1 clache/src

Source

clache.asd.

Parent Component

clache (system).

Child Components

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

3.2 clache/src/stores

Dependency

protocol.lisp (file).

Source

clache.asd.

Parent Component

src (module).

Child Components

4 Files

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


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

4.1 Lisp


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

4.1.1 clache/clache.asd

Source

clache.asd.

Parent Component

clache (system).

ASDF Systems

clache.

Packages

clache-asd.


4.1.2 clache/src/package.lisp

Source

clache.asd.

Parent Component

src (module).

Packages

clache.


4.1.3 clache/src/utils.lisp

Dependency

package.lisp (file).

Source

clache.asd.

Parent Component

src (module).

Internals

4.1.4 clache/src/protocol.lisp

Dependency

utils.lisp (file).

Source

clache.asd.

Parent Component

src (module).

Public Interface
Internals

expire (type).


4.1.5 clache/src/stores/memory.lisp

Source

clache.asd.

Parent Component

stores (module).

Public Interface
Internals

hash-table-of (reader method).


4.1.6 clache/src/stores/file.lisp

Dependency

memory.lisp (file).

Source

clache.asd.

Parent Component

stores (module).

Public Interface
Internals

4.1.7 clache/src/api.lisp

Dependency

stores (module).

Source

clache.asd.

Parent Component

src (module).

Public Interface

5 Packages

Packages are listed by definition order.


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

5.1 clache

Source

package.lisp.

Use List

common-lisp.

Public Interface
Internals

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

5.2 clache-asd

Source

clache.asd.

Use List
  • asdf/interface.
  • common-lisp.

6 Definitions

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


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

6.1 Public Interface


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.

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.

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.


6.1.2 Ordinary functions

Function: clrcache (store)

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

Package

clache.

Source

api.lisp.

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.

Function: (setf getcache) (key store &key expire)
Package

clache.

Source

api.lisp.

Function: never-expire-p (expire)

Return T if EXPIRE represents caches will never be expired.

Package

clache.

Source

protocol.lisp.

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.

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.


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.

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.

Methods
Method: clear-cache ((store file-store))
Source

file.lisp.

Method: clear-cache ((store memory-store))
Source

memory.lisp.

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.

Methods
Method: delete-cache (key (store file-store))
Source

file.lisp.

Method: delete-cache (key (store memory-store))
Source

memory.lisp.

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.

Methods
Method: load-cache (key (store file-store))
Source

file.lisp.

Method: load-cache (key (store memory-store))
Source

memory.lisp.

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.

Methods
Method: store-cache (key value (store file-store) expire)
Source

file.lisp.

Method: store-cache (key value (store memory-store) expire)
Source

memory.lisp.


6.1.4 Classes

Class: file-store
Package

clache.

Source

file.lisp.

Direct superclasses

store.

Direct methods
Direct slots
Slot: directory
Package

common-lisp.

Initform

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

Initargs

:directory

Readers

directory-of.

Writers

This slot is read-only.

Class: memory-store
Package

clache.

Source

memory.lisp.

Direct superclasses

store.

Direct methods
Direct slots
Slot: hash-table
Package

common-lisp.

Initform

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

Initargs

:hash-table

Readers

hash-table-of.

Writers

This slot is read-only.

Class: store

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

Package

clache.

Source

protocol.lisp.

Direct subclasses

6.2 Internals


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

6.2.1 Ordinary functions

Function: cache-path (key store)
Package

clache.

Source

file.lisp.

Function: md5-hex-string (string)

Return a MD5 digest of STRING in hex string.

Package

clache.

Source

utils.lisp.

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.

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.


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

6.2.2 Generic functions

Generic Reader: directory-of (object)
Package

clache.

Methods
Reader Method: directory-of ((file-store file-store))

automatically generated reader method

Source

file.lisp.

Target Slot

directory.

Generic Reader: hash-table-of (object)
Package

clache.

Methods
Reader Method: hash-table-of ((memory-store memory-store))

automatically generated reader method

Source

memory.lisp.

Target Slot

hash-table.


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

6.2.3 Types

Type: expire ()

Type for expiration time.

Package

clache.

Source

protocol.lisp.


Appendix A Indexes


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

A.1 Concepts


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

A.2 Functions

Jump to:   (  
C   D   F   G   H   L   M   N   O   R   S   W  
Index Entry  Section

(
(setf getcache): Public ordinary functions

C
cache: Public macros
cache-key-to-string: Public generic functions
cache-key-to-string: Public generic functions
cache-path: Private ordinary functions
clear-cache: Public generic functions
clear-cache: Public generic functions
clear-cache: Public generic functions
clrcache: Public ordinary functions

D
delete-cache: Public generic functions
delete-cache: Public generic functions
delete-cache: Public generic functions
directory-of: Private generic functions
directory-of: Private generic functions

F
Function, (setf getcache): Public ordinary functions
Function, cache-path: Private ordinary functions
Function, clrcache: Public ordinary functions
Function, getcache: Public ordinary functions
Function, md5-hex-string: Private ordinary functions
Function, never-expire-p: Public ordinary functions
Function, object-to-string: Private ordinary functions
Function, remcache: Public ordinary functions
Function, setcache: Public ordinary functions
Function, symbol-fqn: Private ordinary functions

G
Generic Function, cache-key-to-string: Public generic functions
Generic Function, clear-cache: Public generic functions
Generic Function, delete-cache: Public generic functions
Generic Function, directory-of: Private generic functions
Generic Function, hash-table-of: Private generic functions
Generic Function, load-cache: Public generic functions
Generic Function, store-cache: Public generic functions
getcache: Public ordinary functions

H
hash-table-of: Private generic functions
hash-table-of: Private generic functions

L
load-cache: Public generic functions
load-cache: Public generic functions
load-cache: Public generic functions

M
Macro, cache: Public macros
Macro, with-cache: Public macros
Macro, with-inline-cache: Public macros
md5-hex-string: Private ordinary functions
Method, cache-key-to-string: Public generic functions
Method, clear-cache: Public generic functions
Method, clear-cache: Public generic functions
Method, delete-cache: Public generic functions
Method, delete-cache: Public generic functions
Method, directory-of: Private generic functions
Method, hash-table-of: Private generic functions
Method, load-cache: Public generic functions
Method, load-cache: Public generic functions
Method, store-cache: Public generic functions
Method, store-cache: Public generic functions

N
never-expire-p: Public ordinary functions

O
object-to-string: Private ordinary functions

R
remcache: Public ordinary functions

S
setcache: Public ordinary functions
store-cache: Public generic functions
store-cache: Public generic functions
store-cache: Public generic functions
symbol-fqn: Private ordinary functions

W
with-cache: Public macros
with-inline-cache: Public macros

Jump to:   (  
C   D   F   G   H   L   M   N   O   R   S   W  

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

A.3 Variables

Jump to:   D   H   S  
Index Entry  Section

D
directory: Public classes

H
hash-table: Public classes

S
Slot, directory: Public classes
Slot, hash-table: Public classes

Jump to:   D   H   S  

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

A.4 Data types

Jump to:   A   C   E   F   M   P   S   T   U  
Index Entry  Section

A
api.lisp: The clache/src/api․lisp file

C
clache: The clache system
clache: The clache package
clache-asd: The clache-asd package
clache.asd: The clache/clache․asd file
Class, file-store: Public classes
Class, memory-store: Public classes
Class, store: Public classes

E
expire: Private types

F
File, api.lisp: The clache/src/api․lisp file
File, clache.asd: The clache/clache․asd file
File, file.lisp: The clache/src/stores/file․lisp file
File, memory.lisp: The clache/src/stores/memory․lisp file
File, package.lisp: The clache/src/package․lisp file
File, protocol.lisp: The clache/src/protocol․lisp file
File, utils.lisp: The clache/src/utils․lisp file
file-store: Public classes
file.lisp: The clache/src/stores/file․lisp file

M
memory-store: Public classes
memory.lisp: The clache/src/stores/memory․lisp file
Module, src: The clache/src module
Module, stores: The clache/src/stores module

P
Package, clache: The clache package
Package, clache-asd: The clache-asd package
package.lisp: The clache/src/package․lisp file
protocol.lisp: The clache/src/protocol․lisp file

S
src: The clache/src module
store: Public classes
stores: The clache/src/stores module
System, clache: The clache system

T
Type, expire: Private types

U
utils.lisp: The clache/src/utils․lisp file

Jump to:   A   C   E   F   M   P   S   T   U