The anypool Reference Manual

Table of Contents

The anypool Reference Manual

This is the anypool Reference Manual, version 0.1.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Thu Mar 11 11:25:33 2021 GMT+0.

1 Introduction

anypool

General-purpose connection pooling library.

WARNING

This software is still ALPHA quality. The APIs will be likely to change.

Usage

(ql:quickload '(:anypool :dbi))
(use-package :anypool)

(defvar *connection-pool*
  (make-pool :name "dbi-connections"
             :connector (lambda ()
                          (dbi:connect :postgres
                                       :database-name "webapp"
                                       :username "fukamachi" :password "1ove1isp"))
             :disconnector #'dbi:disconnect
             :ping #'dbi:ping
             :max-open-count 10
             :max-idle-count 2))

(fetch *connection-pool*)
;=> #<DBD.POSTGRES:DBD-POSTGRES-CONNECTION {10054E07C3}>

(pool-open-count *connection-pool*)
;=> 1

(pool-idle-count *connection-pool*)
;=> 0

(putback *** *connection-pool*)
; No value

(pool-open-count *connection-pool*)
;=> 1

(pool-idle-count *connection-pool*)
;=> 1

;; Using `with-connection` macro.
(with-connection (mito:*connection* *connection-pool*)
  (mito:find-dao 'user :name "fukamachi"))

API

[Constructor] make-pool (&key name connector disconnector ping max-open-count max-idle-count timeout idle-timeout)

• :name: The name of a new pool. This is used to print the object.
• :connector (Required): A function to make and return a new connection object. It takes no arguments.
• :disconnector: A function to disconnect a given object. It takes a single argument which is made by :connector.
• :ping: A function to check if the given object is still available. It takes a single argument.
• :max-open-count: The maximum number of concurrently open connections. The default is 4 and can be configured with *default-max-open-count*.
• :max-idle-count: The maximum number of idle/pooled connections. The default is 2 and can be configured with *default-max-idle-count*.
• :timeout: The milliseconds to wait in fetch when the number of open connection reached to the maximum. If nil, it waits forever. The default is nil.
• :idle-timeout: The milliseconds to disconnect idle resources after they're putbacked to the pool. If nil, it won't disconnect automatically. The default is nil.

[Accessor] pool-max-open-count (pool)

Return the maximum number of concurrently open connections. If the number of open connections reached to the limit, fetch waits until a connection is available.

[Accessor] (setf pool-max-open-count) (new-max-open-count pool)

Set the maximum number of concurrently open connections.

[Accessor] pool-max-idle-count (pool)

Return the maximum number of idle/pooled connections. If the number of idle connections reached to the limit, extra connections will be disconnected in putback.

[Accessor] (setf pool-max-idle-count) (new-max-idle-count pool)

Set the maximum number of idle/pooled connections.

[Accessor] pool-idle-timeout (pool)

Return the milliseconds to disconnect idle resources after they're putbacked to the pool. If nil, this feature is disabled.

[Accessor] (setf pool-idle-timeout) (new-idle-timeout pool)

Set the milliseconds to disconnect idle resources after they're putbacked to the pool. If nil, this feature is disabled.

[Accessor] pool-open-count (pool)

Return the number of currently open connections. The count is the sum of pool-active-count and pool-idle-count.

[Accessor] pool-active-count (pool)

Return the number of currently in use connections.

[Accessor] pool-idle-count (pool)

Return the number of currently idle connections.

[Function] fetch (pool)

Return an available resource from the pool. If no open resources available, it makes a new one with a function specified to make-pool as :connector.

No open resource available and can't open due to the max-open-count, this function waits for :timeout milliseconds. If :timeout specified to nil, this waits forever until a new one turns to available.

[Function] putback (object pool)

Send an in-use connection back to pool to make it reusable by other threads. If the number of idle connections is reached to pool-max-idle-count, the connection will be disconnected immediately.

Author

• Eitaro Fukamachi (e.arrows@gmail.com)

Copyright

Copyright (c) 2020 Eitaro Fukamachi (e.arrows@gmail.com)

License

Licensed under the BSD 2-Clause License.

2 Systems

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

2.1 anypool

Author

Eitaro Fukamachi

License

BSD 2-Clause

Description

General-purpose pooling library

Version

0.1.0

Dependencies

• bordeaux-threads
• cl-speedy-queue

Source

anypool.asd (file)

Component

src (module)

3 Modules

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

3.1 anypool/src

Parent

anypool (system)

Location

src/

Component

main.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 anypool.asd

Location

anypool.asd

Systems

anypool (system)

4.1.2 anypool/src/main.lisp

Parent

src (module)

Location

src/main.lisp

Packages

anypool

Exported Definitions

• *default-max-idle-count* (special variable)
• *default-max-open-count* (special variable)
• error-max-open-limit (method)
• fetch (function)
• make-pool (function)
• pool (structure)
• pool-active-count (function)
• (setf pool-active-count) (function)
• pool-idle-count (function)
• pool-idle-timeout (function)
• (setf pool-idle-timeout) (function)
• pool-max-idle-count (function)
• (setf pool-max-idle-count) (function)
• pool-max-open-count (function)
• (setf pool-max-open-count) (function)
• pool-name (function)
• (setf pool-name) (function)
• pool-open-count (function)
• putback (function)
• too-many-open-connection (condition)
• with-connection (macro)

Internal Definitions

• anypool-error (condition)
• copy-item (function)
• copy-pool (function)
• dequeue-timeout-resources (function)
• item (structure)
• item-idle-timer (function)
• (setf item-idle-timer) (function)
• item-object (function)
• (setf item-object) (function)
• item-p (function)
• item-timeout-p (function)
• (setf item-timeout-p) (function)
• make-idle-timer (function)
• make-item (function)
• make-queue* (function)
• pool-connector (function)
• (setf pool-connector) (function)
• pool-disconnector (function)
• (setf pool-disconnector) (function)
• pool-lock (function)
• (setf pool-lock) (function)
• pool-p (function)
• pool-ping (function)
• (setf pool-ping) (function)
• pool-storage (function)
• (setf pool-storage) (function)
• pool-timeout (function)
• (setf pool-timeout) (function)
• pool-timeout-in-queue-count (function)
• (setf pool-timeout-in-queue-count) (function)
• pool-wait-condvar (function)
• (setf pool-wait-condvar) (function)
• pool-wait-lock (function)
• (setf pool-wait-lock) (function)
• queue-peek* (function)

5 Packages

Packages are listed by definition order.

5.1 anypool

Source

main.lisp (file)

Nickname

anypool/main

Use List

common-lisp

Exported Definitions

• *default-max-idle-count* (special variable)
• *default-max-open-count* (special variable)
• error-max-open-limit (generic function)
• error-max-open-limit (method)
• fetch (function)
• make-pool (function)
• pool (structure)
• pool-active-count (function)
• (setf pool-active-count) (function)
• pool-idle-count (function)
• pool-idle-timeout (function)
• (setf pool-idle-timeout) (function)
• pool-max-idle-count (function)
• (setf pool-max-idle-count) (function)
• pool-max-open-count (function)
• (setf pool-max-open-count) (function)
• pool-name (function)
• (setf pool-name) (function)
• pool-open-count (function)
• putback (function)
• too-many-open-connection (condition)
• with-connection (macro)

Internal Definitions

• anypool-error (condition)
• copy-item (function)
• copy-pool (function)
• dequeue-timeout-resources (function)
• item (structure)
• item-idle-timer (function)
• (setf item-idle-timer) (function)
• item-object (function)
• (setf item-object) (function)
• item-p (function)
• item-timeout-p (function)
• (setf item-timeout-p) (function)
• make-idle-timer (function)
• make-item (function)
• make-queue* (function)
• pool-connector (function)
• (setf pool-connector) (function)
• pool-disconnector (function)
• (setf pool-disconnector) (function)
• pool-lock (function)
• (setf pool-lock) (function)
• pool-p (function)
• pool-ping (function)
• (setf pool-ping) (function)
• pool-storage (function)
• (setf pool-storage) (function)
• pool-timeout (function)
• (setf pool-timeout) (function)
• pool-timeout-in-queue-count (function)
• (setf pool-timeout-in-queue-count) (function)
• pool-wait-condvar (function)
• (setf pool-wait-condvar) (function)
• pool-wait-lock (function)
• (setf pool-wait-lock) (function)
• queue-peek* (function)

6 Definitions

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

6.1 Exported definitions

6.1.1 Special variables

Special Variable: *default-max-idle-count*

Package

anypool

Source

main.lisp (file)

Special Variable: *default-max-open-count*

Package

anypool

Source

main.lisp (file)

6.1.2 Macros

Macro: with-connection (CONN POOL) &body BODY

Package

anypool

Source

main.lisp (file)

6.1.3 Functions

Function: fetch POOL

Package

anypool

Source

main.lisp (file)

Function: make-pool &key NAME CONNECTOR DISCONNECTOR PING MAX-OPEN-COUNT MAX-IDLE-COUNT TIMEOUT IDLE-TIMEOUT &aux STORAGE

Package

anypool

Source

main.lisp (file)

Function: pool-active-count INSTANCE

Function: (setf pool-active-count) VALUE INSTANCE

Package

anypool

Source

main.lisp (file)

Function: pool-idle-count POOL

Package

anypool

Source

main.lisp (file)

Function: pool-idle-timeout INSTANCE

Function: (setf pool-idle-timeout) VALUE INSTANCE

Package

anypool

Source

main.lisp (file)

Function: pool-max-idle-count INSTANCE

Function: (setf pool-max-idle-count) VALUE INSTANCE

Package

anypool

Source

main.lisp (file)

Function: pool-max-open-count INSTANCE

Function: (setf pool-max-open-count) VALUE INSTANCE

Package

anypool

Source

main.lisp (file)

Function: pool-name INSTANCE

Function: (setf pool-name) VALUE INSTANCE

Package

anypool

Source

main.lisp (file)

Function: pool-open-count POOL

Package

anypool

Source

main.lisp (file)

Function: putback CONN POOL

Package

anypool

Source

main.lisp (file)

6.1.4 Generic functions

Generic Function: error-max-open-limit CONDITION

Package

anypool

Methods

Method: error-max-open-limit (CONDITION too-many-open-connection)

Source

main.lisp (file)

6.1.5 Conditions

Condition: too-many-open-connection ()

Package

anypool

Source

main.lisp (file)

Direct superclasses

anypool-error (condition)

Direct methods

error-max-open-limit (method)

Direct slots

Slot: limit

Initargs

:limit

Readers

error-max-open-limit (generic function)

6.1.6 Structures

Structure: pool ()

Package

anypool

Source

main.lisp (file)

Direct superclasses

structure-object (structure)

Direct methods

print-object (method)

Direct slots

Slot: name

Readers

pool-name (function)

Writers

(setf pool-name) (function)

Slot: connector

Readers

pool-connector (function)

Writers

(setf pool-connector) (function)

Slot: disconnector

Readers

pool-disconnector (function)

Writers

(setf pool-disconnector) (function)

Slot: ping

Readers

pool-ping (function)

Writers

(setf pool-ping) (function)

Slot: max-open-count

Readers

pool-max-open-count (function)

Writers

(setf pool-max-open-count) (function)

Slot: max-idle-count

Readers

pool-max-idle-count (function)

Writers

(setf pool-max-idle-count) (function)

Slot: idle-timeout

Readers

pool-idle-timeout (function)

Writers

(setf pool-idle-timeout) (function)

Slot: timeout

Readers

pool-timeout (function)

Writers

(setf pool-timeout) (function)

Slot: storage

Readers

pool-storage (function)

Writers

(setf pool-storage) (function)

Slot: active-count

Type

fixnum

Initform

0

Readers

pool-active-count (function)

Writers

(setf pool-active-count) (function)

Slot: timeout-in-queue-count

Type

fixnum

Initform

0

Readers

pool-timeout-in-queue-count (function)

Writers

(setf pool-timeout-in-queue-count) (function)

Slot: lock

Initform

(bordeaux-threads:make-lock "anypool-lock")

Readers

pool-lock (function)

Writers

(setf pool-lock) (function)

Slot: wait-lock

Initform

(bordeaux-threads:make-lock "anypool-openwait-lock")

Readers

pool-wait-lock (function)

Writers

(setf pool-wait-lock) (function)

Slot: wait-condvar

Initform

(bordeaux-threads:make-condition-variable :name "anypool-openwait")

Readers

pool-wait-condvar (function)

Writers

(setf pool-wait-condvar) (function)

6.2 Internal definitions

6.2.1 Functions

Function: copy-item INSTANCE

Package

anypool

Source

main.lisp (file)

Function: copy-pool INSTANCE

Package

anypool

Source

main.lisp (file)

Function: dequeue-timeout-resources POOL

Package

anypool

Source

main.lisp (file)

Function: item-idle-timer INSTANCE

Function: (setf item-idle-timer) VALUE INSTANCE

Package

anypool

Source

main.lisp (file)

Function: item-object INSTANCE

Function: (setf item-object) VALUE INSTANCE

Package

anypool

Source

main.lisp (file)

Function: item-p OBJECT

Package

anypool

Source

main.lisp (file)

Function: item-timeout-p INSTANCE

Function: (setf item-timeout-p) VALUE INSTANCE

Package

anypool

Source

main.lisp (file)

Function: make-idle-timer ITEM TIMEOUT-FN

Package

anypool

Source

main.lisp (file)

Function: make-item OBJECT

Package

anypool

Source

main.lisp (file)

Function: make-queue* SIZE

Package

anypool

Source

main.lisp (file)

Function: pool-connector INSTANCE

Function: (setf pool-connector) VALUE INSTANCE

Package

anypool

Source

main.lisp (file)

Function: pool-disconnector INSTANCE

Function: (setf pool-disconnector) VALUE INSTANCE

Package

anypool

Source

main.lisp (file)

Function: pool-lock INSTANCE

Function: (setf pool-lock) VALUE INSTANCE

Package

anypool

Source

main.lisp (file)

Function: pool-p OBJECT

Package

anypool

Source

main.lisp (file)

Function: pool-ping INSTANCE

Function: (setf pool-ping) VALUE INSTANCE

Package

anypool

Source

main.lisp (file)

Function: pool-storage INSTANCE

Function: (setf pool-storage) VALUE INSTANCE

Package

anypool

Source

main.lisp (file)

Function: pool-timeout INSTANCE

Function: (setf pool-timeout) VALUE INSTANCE

Package

anypool

Source

main.lisp (file)

Function: pool-timeout-in-queue-count INSTANCE

Function: (setf pool-timeout-in-queue-count) VALUE INSTANCE

Package

anypool

Source

main.lisp (file)

Function: pool-wait-condvar INSTANCE

Function: (setf pool-wait-condvar) VALUE INSTANCE

Package

anypool

Source

main.lisp (file)

Function: pool-wait-lock INSTANCE

Function: (setf pool-wait-lock) VALUE INSTANCE

Package

anypool

Source

main.lisp (file)

Function: queue-peek* QUEUE

Package

anypool

Source

main.lisp (file)

6.2.2 Conditions

Condition: anypool-error ()

Package

anypool

Source

main.lisp (file)

Direct superclasses

error (condition)

Direct subclasses

too-many-open-connection (condition)

6.2.3 Structures

Structure: item ()

Package

anypool

Source

main.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots

Slot: object

Readers

item-object (function)

Writers

(setf item-object) (function)

Slot: idle-timer

Readers

item-idle-timer (function)

Writers

(setf item-idle-timer) (function)

Slot: timeout-p

Readers

item-timeout-p (function)

Writers

(setf item-timeout-p) (function)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types