The pooler Reference Manual

Table of Contents

The pooler Reference Manual

This is the pooler Reference Manual, version 1.0.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 17:25:25 2021 GMT+0.

1 Introduction

Pooler

A Trivial, Fast, Thread-Safe Pooling Library for Common Lisp.

We need pools for items which have heavy cost of creation and which we can reuse. A typical use case is connection pools.

Pool item creation (as required) is automatic on fetch-from pool. Pool-item's are created and destroyed using user supplied funcitons. The pool has a idle timeout after which all the existing pool-item's are destroyed and new ones created (pool-init). The pool has a threshold number of items which it tries to maintain.

Licence : MIT

API

Structure POOL

NAME             : Is a text string identifying the POOL
QUEUE            : A queue to store the POOL-ITEMs
POOL-LOCK        : A lock we hold when we want to update the POOL
ITEM-MAKER       : A function which returns a POOL-ITEM.
ITEM-DESTROYER   : A function which sanely destroys a POOL-ITEM
CAPACITY         : The max number of POOL-ITEMs to store in the POOL
THRESHOLD        : The min number of POOL-ITEMs we should ideally keep in the POOL.
TIMEOUT          : The number of seconds of idleness after which the POOL will be re-init.
LAST-ACCESS      : The last access time for the POOL.
CURRENT-SIZE     : The current number of POOL-ITEMs in the POOL
TOTAL-USES       : Total number of times the POOL-ITEMs have been taken out of the POOL
TOTAL-CREATED    : Total number of new POOL-ITEMs created and added to the POOL
TOTAL-POOL-INITS : How many times the POOL was 'INIT'.

make-pool &key name max-capacity min-threshold pool-item-maker pool-item-destroyer

Makes and returns a new POOL.

grow-pool pool &optional grow-by

Creates and adds POOL-ITEMs to the pool. In case grow-by is not provided then it takes ( threshold pool ) as the value

fetch-from-aux pool

Fetches a POOL-ITEM from the POOL. Tell us if the pool has become old.

fetch-from pool &key (tries 3)

Is a wrapper around fetch-from-aux and will try tries number of times to fetch POOL-ITEM from POOL. In case POOL-ITEM is not returned then it grows the POOL and tries again.

return-to pool pool-item

Returns a POOL-ITEM to the POOL. In case the pool is at CAPACITY the POOL-ITEM will be sanely destroyed using the given function

pool-init pool

Sanely destroys all the POOL-ITEMS and then re-creates THRESHOLD number of POOL-ITEMS.

with-pool pool-item pool &body body

Executes the body where pool-item is fetched from the pool and available. Sanely returns pool-item to the pool on finish of body.

Examples

POOLER> (defvar *x* nil)
*X*
POOLER> (setf *x* (make-pool :name "Test Pool"))
#<POOL Test Pool Max:4 Current:0 >
POOLER> (fetch-from+ *x*)
SAMPLE-ITEM
POOLER> *x*
#<POOL Test Pool Max:4 Current:1 >
POOLER> (return-to *x* **)
2
POOLER> (with-pool (pool-item *x*) (print pool-item))
SAMPLE-ITEM
SAMPLE-ITEM
POOLER> *x*
#<POOL Test Pool Max:4 Current:2 >

Another

CL-USER> (pooler:make-pool :item-maker #'(lambda () (clsql:connect '("127.0.0.1" "quasidb" "quasi" "*****")
                                                                    :database-type :mysql
                                                                    :if-exists :new))
                           :item-destroyer #'(lambda (item) (clsql:disconnect :database item)))
#S(POOLER::POOL
  :NAME "Default Pool"
  :QUEUE #S(SB-CONCURRENCY:QUEUE
  :HEAD (SB-CONCURRENCY::.DUMMY.)
  :TAIL (SB-CONCURRENCY::.DUMMY.)
  :NAME NIL)
  :LOCK #<SB-THREAD:MUTEX "Pool Lock" (free)>
  :ITEM-MAKER #<FUNCTION (LAMBDA #) {1005C9BFAB}>
  :ITEM-DESTROYER #<FUNCTION (LAMBDA #) {1005CCAAAB}>
  :CAPACITY 40
  :THRESHOLD 2
  :TIMEOUT 300
  :LAST-ACCESS 0
  :CURRENT-SIZE 0
  :TOTAL-USES 0
  :TOTAL-CREATED 0
  :TOTAL-POOL-INITS 0)
CL-USER> (defvar *mysql-pool* *)
CL-USER> (pooler:fetch-from *mysql-pool*)
#<CLSQL-MYSQL:MYSQL-DATABASE 127.0.0.1/quasidb/quasi OPEN {1007571373}>
CL-USER> (pooler:return-to *mysql-pool* *)
2
CL-USER> (pooler:with-pool (db *mysql-pool*) (clsql:query "show tables;" :database db))
(("LOGIN_DATA"))
("Tables_in_quasidb")

Author

Abhijit Rao a.k.a quasi

quasi@quasilabs.in

2 Systems

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

2.1 pooler

Author

quasi <quasi@quasilabs.in>

License

MIT

Description

Generic thread-safe pooling facility for your library.

Long Description

A Trivial, Fast & Thread-Safe Pooling Library for Common Lisp.

We need pools for items which have heavy cost of creation and which we can reuse. A typical use case is connection pools.

Pool item creation (as required) is automatic on fetch-from pool. Pool-item’s are created and destroyed using user supplied funcitons. The pool has a idle timeout after which all the existing pool-item’s are destroyed and new ones created (pool-init). The pool has a threshold number of items which it tries to maintain.

Version

1.0.0

Dependency

sb-concurrency

Source

pooler.asd (file)

Components

• package.lisp (file)
• utils.lisp (file)
• pooler.lisp (file)

3 Files

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

3.1 Lisp

3.1.1 pooler.asd

Location

pooler.asd

Systems

pooler (system)

3.1.2 pooler/package.lisp

Parent

pooler (system)

Location

package.lisp

Packages

pooler

3.1.3 pooler/utils.lisp

Dependency

package.lisp (file)

Parent

pooler (system)

Location

utils.lisp

Internal Definitions

• copy-q (function)
• dequeue (macro)
• empty-queue? (function)
• enqueue (macro)
• enqueue-at-end (function)
• make-empty-queue (function)
• make-pool-lock (function)
• make-q (function)
• make-queue (function)
• q (structure)
• q-elements (function)
• (setf q-elements) (function)
• q-key (function)
• (setf q-key) (function)
• q-last (function)
• (setf q-last) (function)
• q-p (function)
• queue-empty-p (macro)
• queue-front (function)
• remove-front (function)
• with-pool-lock (macro)

3.1.4 pooler/pooler.lisp

Dependency

utils.lisp (file)

Parent

pooler (system)

Location

pooler.lisp

Exported Definitions

• fetch-from (function)
• grow-pool (function)
• make-pool (function)
• pool-init (function)
• return-to (function)
• with-pool (macro)

Internal Definitions

• copy-pool (function)
• destroy-pool-item (function)
• fetch-from-aux (function)
• message (method)
• (setf message) (method)
• message (method)
• (setf message) (method)
• name (method)
• (setf name) (method)
• new-pool-item (function)
• pool (structure)
• pool-capacity (function)
• (setf pool-capacity) (function)
• pool-current-size (function)
• (setf pool-current-size) (function)
• pool-empty-error (condition)
• pool-error (function)
• pool-error (condition)
• pool-item-creation-error (condition)
• pool-item-destroyer (function)
• pool-item-maker (function)
• pool-last-access (function)
• (setf pool-last-access) (function)
• pool-lock (function)
• pool-name (function)
• pool-p (function)
• pool-queue (function)
• (setf pool-queue) (function)
• pool-threshold (function)
• (setf pool-threshold) (function)
• pool-timeout (function)
• (setf pool-timeout) (function)
• pool-total-created (function)
• (setf pool-total-created) (function)
• pool-total-pool-inits (function)
• (setf pool-total-pool-inits) (function)
• pool-total-uses (function)
• (setf pool-total-uses) (function)
• pool-warning (condition)

4 Packages

Packages are listed by definition order.

4.1 pooler

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions

• fetch-from (function)
• grow-pool (function)
• make-pool (function)
• pool-init (function)
• return-to (function)
• with-pool (macro)

Internal Definitions

• copy-pool (function)
• copy-q (function)
• dequeue (macro)
• destroy-pool-item (function)
• empty-queue? (function)
• enqueue (macro)
• enqueue-at-end (function)
• fetch-from-aux (function)
• make-empty-queue (function)
• make-pool-lock (function)
• make-q (function)
• make-queue (function)
• message (generic function)
• message (method)
• (setf message) (method)
• message (method)
• (setf message) (method)
• (setf message) (generic function)
• name (generic function)
• name (method)
• (setf name) (method)
• (setf name) (generic function)
• new-pool-item (function)
• pool (structure)
• pool-capacity (function)
• (setf pool-capacity) (function)
• pool-current-size (function)
• (setf pool-current-size) (function)
• pool-empty-error (condition)
• pool-error (function)
• pool-error (condition)
• pool-item-creation-error (condition)
• pool-item-destroyer (function)
• pool-item-maker (function)
• pool-last-access (function)
• (setf pool-last-access) (function)
• pool-lock (function)
• pool-name (function)
• pool-p (function)
• pool-queue (function)
• (setf pool-queue) (function)
• pool-threshold (function)
• (setf pool-threshold) (function)
• pool-timeout (function)
• (setf pool-timeout) (function)
• pool-total-created (function)
• (setf pool-total-created) (function)
• pool-total-pool-inits (function)
• (setf pool-total-pool-inits) (function)
• pool-total-uses (function)
• (setf pool-total-uses) (function)
• pool-warning (condition)
• q (structure)
• q-elements (function)
• (setf q-elements) (function)
• q-key (function)
• (setf q-key) (function)
• q-last (function)
• (setf q-last) (function)
• q-p (function)
• queue-empty-p (macro)
• queue-front (function)
• remove-front (function)
• with-pool-lock (macro)

5 Definitions

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

5.1 Exported definitions

5.1.1 Macros

Macro: with-pool (POOL-ITEM POOL) &body BODY

Package

pooler

Source

pooler.lisp (file)

5.1.2 Functions

Function: fetch-from POOL &key TRIES

Tries a couple of times to fetch from pool. Grows the pool.

Package

pooler

Source

pooler.lisp (file)

Function: grow-pool POOL &optional GROW-BY

Package

pooler

Source

pooler.lisp (file)

Function: make-pool &key NAME CAPACITY THRESHOLD ITEM-MAKER ITEM-DESTROYER TIMEOUT

Package

pooler

Source

pooler.lisp (file)

Function: pool-init POOL

Cleans up the pool & reinits it with MIN-THRESHOLD number of POOL-ITEM

Package

pooler

Source

pooler.lisp (file)

Function: return-to POOL POOL-ITEM

Returns a pool object to the pool

Package

pooler

Source

pooler.lisp (file)

5.2 Internal definitions

5.2.1 Macros

Macro: dequeue QUEUE

Package

pooler

Source

utils.lisp (file)

Macro: enqueue QUEUE WHAT

Package

pooler

Source

utils.lisp (file)

Macro: queue-empty-p QUEUE

Package

pooler

Source

utils.lisp (file)

Macro: with-pool-lock (LOCK) &body BODY

Package

pooler

Source

utils.lisp (file)

5.2.2 Functions

Function: copy-pool INSTANCE

Package

pooler

Source

pooler.lisp (file)

Function: copy-q INSTANCE

Package

pooler

Source

utils.lisp (file)

Function: destroy-pool-item POOL POOL-ITEM

Destroys the POOL-ITEM using the item-destroyer funciton stored in the pool

Package

pooler

Source

pooler.lisp (file)

Function: empty-queue? Q

Are there no elements in the queue?

Package

pooler

Source

utils.lisp (file)

Function: enqueue-at-end Q ITEMS

Add a list of items to the end of the queue.

Package

pooler

Source

utils.lisp (file)

Function: fetch-from-aux POOL &optional OLD

Fetches a pool item from pool.

Package

pooler

Source

pooler.lisp (file)

Function: make-empty-queue ()

Package

pooler

Source

utils.lisp (file)

Function: make-pool-lock ()

Package

pooler

Source

utils.lisp (file)

Function: make-q &key (KEY KEY) (LAST LAST) (ELEMENTS ELEMENTS)

Package

pooler

Source

utils.lisp (file)

Function: make-queue ()

Package

pooler

Source

utils.lisp (file)

Function: new-pool-item POOL

Creates a new POOL-ITEM using the item-maker funciton stored in the pool

Package

pooler

Source

pooler.lisp (file)

Function: pool-capacity INSTANCE

Function: (setf pool-capacity) VALUE INSTANCE

Package

pooler

Source

pooler.lisp (file)

Function: pool-current-size INSTANCE

Function: (setf pool-current-size) VALUE INSTANCE

Package

pooler

Source

pooler.lisp (file)

Function: pool-error MESSAGE &key POOL-NAME

Signals an error of type POOL-ERROR with the provided information

Package

pooler

Source

pooler.lisp (file)

Function: pool-item-destroyer INSTANCE

Package

pooler

Source

pooler.lisp (file)

Function: pool-item-maker INSTANCE

Package

pooler

Source

pooler.lisp (file)

Function: pool-last-access INSTANCE

Function: (setf pool-last-access) VALUE INSTANCE

Package

pooler

Source

pooler.lisp (file)

Function: pool-lock INSTANCE

Package

pooler

Source

pooler.lisp (file)

Function: pool-name INSTANCE

Package

pooler

Source

pooler.lisp (file)

Function: pool-p OBJECT

Package

pooler

Source

pooler.lisp (file)

Function: pool-queue INSTANCE

Function: (setf pool-queue) VALUE INSTANCE

Package

pooler

Source

pooler.lisp (file)

Function: pool-threshold INSTANCE

Function: (setf pool-threshold) VALUE INSTANCE

Package

pooler

Source

pooler.lisp (file)

Function: pool-timeout INSTANCE

Function: (setf pool-timeout) VALUE INSTANCE

Package

pooler

Source

pooler.lisp (file)

Function: pool-total-created INSTANCE

Function: (setf pool-total-created) VALUE INSTANCE

Package

pooler

Source

pooler.lisp (file)

Function: pool-total-pool-inits INSTANCE

Function: (setf pool-total-pool-inits) VALUE INSTANCE

Package

pooler

Source

pooler.lisp (file)

Function: pool-total-uses INSTANCE

Function: (setf pool-total-uses) VALUE INSTANCE

Package

pooler

Source

pooler.lisp (file)

Function: q-elements INSTANCE

Function: (setf q-elements) VALUE INSTANCE

Package

pooler

Source

utils.lisp (file)

Function: q-key INSTANCE

Function: (setf q-key) VALUE INSTANCE

Package

pooler

Source

utils.lisp (file)

Function: q-last INSTANCE

Function: (setf q-last) VALUE INSTANCE

Package

pooler

Source

utils.lisp (file)

Function: q-p OBJECT

Package

pooler

Source

utils.lisp (file)

Function: queue-front Q

Return the element at the front of the queue.

Package

pooler

Source

utils.lisp (file)

Function: remove-front Q

Remove the element from the front of the queue and return it.

Package

pooler

Source

utils.lisp (file)

5.2.3 Generic functions

Generic Function: message CONDITION

Generic Function: (setf message) NEW-VALUE CONDITION

Package

pooler

Methods

Method: message (CONDITION pool-warning)

Method: (setf message) NEW-VALUE (CONDITION pool-warning)

Source

pooler.lisp (file)

Method: message (CONDITION pool-error)

Method: (setf message) NEW-VALUE (CONDITION pool-error)

Source

pooler.lisp (file)

Generic Function: name CONDITION

Generic Function: (setf name) NEW-VALUE CONDITION

Package

pooler

Methods

Method: name (CONDITION pool-error)

Method: (setf name) NEW-VALUE (CONDITION pool-error)

Source

pooler.lisp (file)

5.2.4 Conditions

Condition: pool-empty-error ()

Package

pooler

Source

pooler.lisp (file)

Direct superclasses

pool-error (condition)

Condition: pool-error ()

Superclass for all errors related to Pooler.

Package

pooler

Source

pooler.lisp (file)

Direct superclasses

error (condition)

Direct subclasses

• pool-item-creation-error (condition)
• pool-empty-error (condition)

Direct methods

• name (method)
• name (method)
• message (method)
• message (method)

Direct slots

Slot: message

Initargs

:message

Initform

(quote nil)

Readers

message (generic function)

Writers

(setf message) (generic function)

Slot: name

Initargs

:name

Initform

(quote nil)

Readers

name (generic function)

Writers

(setf name) (generic function)

Condition: pool-item-creation-error ()

Package

pooler

Source

pooler.lisp (file)

Direct superclasses

pool-error (condition)

Condition: pool-warning ()

Package

pooler

Source

pooler.lisp (file)

Direct superclasses

warning (condition)

Direct methods

• message (method)
• message (method)

Direct slots

Slot: message

Initargs

:message

Initform

(quote nil)

Readers

message (generic function)

Writers

(setf message) (generic function)

5.2.5 Structures

Structure: pool ()

Package

pooler

Source

pooler.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots

Slot: name

Type

simple-string

Initform

"default pool"

Readers

pool-name (function)

Writers

(setf pool-name) (function)

Slot: queue

Initform

(pooler::make-queue)

Readers

pool-queue (function)

Writers

(setf pool-queue) (function)

Slot: lock

Initform

(pooler::make-pool-lock)

Readers

pool-lock (function)

Writers

(setf pool-lock) (function)

Slot: item-maker

Type

function

Initform

(function (lambda nil (quote pooler::sample-item)))

Readers

pool-item-maker (function)

Writers

(setf pool-item-maker) (function)

Slot: item-destroyer

Type

function

Initform

(function (lambda (pooler::item) (setf pooler::item nil)))

Readers

pool-item-destroyer (function)

Writers

(setf pool-item-destroyer) (function)

Slot: capacity

Type

fixnum

Initform

40

Readers

pool-capacity (function)

Writers

(setf pool-capacity) (function)

Slot: threshold

Type

fixnum

Initform

2

Readers

pool-threshold (function)

Writers

(setf pool-threshold) (function)

Slot: timeout

Type

fixnum

Initform

300

Readers

pool-timeout (function)

Writers

(setf pool-timeout) (function)

Slot: last-access

Type

integer

Initform

0

Readers

pool-last-access (function)

Writers

(setf pool-last-access) (function)

Slot: current-size

Type

fixnum

Initform

0

Readers

pool-current-size (function)

Writers

(setf pool-current-size) (function)

Slot: total-uses

Type

fixnum

Initform

0

Readers

pool-total-uses (function)

Writers

(setf pool-total-uses) (function)

Slot: total-created

Type

fixnum

Initform

0

Readers

pool-total-created (function)

Writers

(setf pool-total-created) (function)

Slot: total-pool-inits

Type

fixnum

Initform

0

Readers

pool-total-pool-inits (function)

Writers

(setf pool-total-pool-inits) (function)

Structure: q ()

Package

pooler

Source

utils.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots

Slot: key

Initform

(function identity)

Readers

q-key (function)

Writers

(setf q-key) (function)

Slot: last

Readers

q-last (function)

Writers

(setf q-last) (function)

Slot: elements

Readers

q-elements (function)

Writers

(setf q-elements) (function)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types