The clache Reference Manual

Table of Contents

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

The clache Reference Manual

This is the clache Reference Manual, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 03:37:58 2018 GMT+0.


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

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>


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 clache

Maintainer

Olexiy Zamkoviy

Author

Tomohiro Matsuyama

License

LLGPL

Dependencies
Source

clache.asd (file)

Component

src (module)


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

3 Modules

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


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

3.1 clache/src

Parent

clache (system)

Location

src/

Components

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

3.2 clache/src/stores

Dependency

protocol.lisp (file)

Parent

src (module)

Location

src/stores/

Components

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

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 files   [Contents][Index]

4.1.1 clache.asd

Location

clache.asd

Systems

clache (system)

Packages

clache-asd


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

4.1.2 clache/src/package.lisp

Parent

src (module)

Location

src/package.lisp

Packages

clache


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

4.1.3 clache/src/utils.lisp

Dependency

package.lisp (file)

Parent

src (module)

Location

src/utils.lisp

Internal Definitions

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

4.1.4 clache/src/protocol.lisp

Dependency

utils.lisp (file)

Parent

src (module)

Location

src/protocol.lisp

Exported Definitions
Internal Definitions

expire (type)


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

4.1.5 clache/src/stores/memory.lisp

Parent

stores (module)

Location

src/stores/memory.lisp

Exported Definitions
Internal Definitions

hash-table-of (method)


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

4.1.6 clache/src/stores/file.lisp

Dependency

memory.lisp (file)

Parent

stores (module)

Location

src/stores/file.lisp

Exported Definitions
Internal Definitions

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

4.1.7 clache/src/api.lisp

Dependency

stores (module)

Parent

src (module)

Location

src/api.lisp

Exported Definitions

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

5 Packages

Packages are listed by definition order.


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

5.1 clache-asd

Source

clache.asd

Use List

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

5.2 clache

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

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

6 Definitions

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


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

6.1 Exported definitions


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

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)


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

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)


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

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)


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

6.1.4 Classes

Class: file-store ()
Package

clache

Source

file.lisp (file)

Direct superclasses

store (class)

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

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

6.2 Internal definitions


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

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)


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

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)


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

6.2.3 Types

Type: expire ()

Type for expiration time.

Package

clache

Source

protocol.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   C   F   L   M  
Index Entry  Section

C
clache.asd: The clache<dot>asd file
clache/src: The clache/src module
clache/src/api.lisp: The clache/src/api<dot>lisp file
clache/src/package.lisp: The clache/src/package<dot>lisp file
clache/src/protocol.lisp: The clache/src/protocol<dot>lisp file
clache/src/stores: The clache/src/stores module
clache/src/stores/file.lisp: The clache/src/stores/file<dot>lisp file
clache/src/stores/memory.lisp: The clache/src/stores/memory<dot>lisp file
clache/src/utils.lisp: The clache/src/utils<dot>lisp file

F
File, Lisp, clache.asd: The clache<dot>asd file
File, Lisp, clache/src/api.lisp: The clache/src/api<dot>lisp file
File, Lisp, clache/src/package.lisp: The clache/src/package<dot>lisp file
File, Lisp, clache/src/protocol.lisp: The clache/src/protocol<dot>lisp file
File, Lisp, clache/src/stores/file.lisp: The clache/src/stores/file<dot>lisp file
File, Lisp, clache/src/stores/memory.lisp: The clache/src/stores/memory<dot>lisp file
File, Lisp, clache/src/utils.lisp: The clache/src/utils<dot>lisp file

L
Lisp File, clache.asd: The clache<dot>asd file
Lisp File, clache/src/api.lisp: The clache/src/api<dot>lisp file
Lisp File, clache/src/package.lisp: The clache/src/package<dot>lisp file
Lisp File, clache/src/protocol.lisp: The clache/src/protocol<dot>lisp file
Lisp File, clache/src/stores/file.lisp: The clache/src/stores/file<dot>lisp file
Lisp File, clache/src/stores/memory.lisp: The clache/src/stores/memory<dot>lisp file
Lisp File, clache/src/utils.lisp: The clache/src/utils<dot>lisp file

M
Module, clache/src: The clache/src module
Module, clache/src/stores: The clache/src/stores module

Jump to:   C   F   L   M  

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): Exported functions

C
cache: Exported macros
cache-key-to-string: Exported generic functions
cache-key-to-string: Exported generic functions
cache-path: Internal functions
clear-cache: Exported generic functions
clear-cache: Exported generic functions
clear-cache: Exported generic functions
clrcache: Exported functions

D
delete-cache: Exported generic functions
delete-cache: Exported generic functions
delete-cache: Exported generic functions
directory-of: Internal generic functions
directory-of: Internal generic functions

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

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

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

L
load-cache: Exported generic functions
load-cache: Exported generic functions
load-cache: Exported generic functions

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

N
never-expire-p: Exported functions

O
object-to-string: Internal functions

R
remcache: Exported functions

S
setcache: Exported functions
store-cache: Exported generic functions
store-cache: Exported generic functions
store-cache: Exported generic functions
symbol-fqn: Internal functions

W
with-cache: Exported macros
with-inline-cache: Exported 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: Exported classes

H
hash-table: Exported classes

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

Jump to:   D   H   S  

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

A.4 Data types

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

C
clache: The clache system
clache: The clache package
clache-asd: The clache-asd package
Class, file-store: Exported classes
Class, memory-store: Exported classes
Class, store: Exported classes

E
expire: Internal types

F
file-store: Exported classes

M
memory-store: Exported classes

P
Package, clache: The clache package
Package, clache-asd: The clache-asd package

S
store: Exported classes
System, clache: The clache system

T
Type, expire: Internal types

Jump to:   C   E   F   M   P   S   T