The cl-threadpool Reference Manual

Table of Contents

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

The cl-threadpool Reference Manual

This is the cl-threadpool Reference Manual, version 1.0.0, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 03:35:11 2018 GMT+0.


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

1 Introduction

cl-threadpool

A Thread pool implemented in Common Lisp

The thread pool consists of a fixed number of worker threads and a job queue. The worker threads are picking jobs from the queue and execute them.

Installation

Download cl-threadpool and add it to the asdf-system path. This step is required as long as cl-threadpool is not available via quicklisp.

Install (downloads and installs all dependencies)

(ql:quickload "cl-threadpool")

Dependencies:

Example

Load cl-threadpool

(asdf:load-system "cl-threadpool")

Create a thread pool with 5 worker threads

(defparameter *threadpool* (cl-threadpool:make-threadpool 5))

Start the pool

(cl-threadpool:start *threadpool*)

Add a job

(cl-threadpool:add-job
   *threadpool*
   (lambda () (sleep 5)))

Stop the pool

(cl-threadpool:stop *threadpool*)

API

More detailed documentation is provided by the documentation strings of the functions.

Condition-Types

Logging

The thread pool uses the Verbose framework for logging.

Disable logging of the cl-threadpool package

(setf (v:repl-categories) (v:remove-repl-category (list :cl-threadpool)))

Set logging level (globally)

(setf (v:repl-level) :error)

Running the tests

The tests are using the lisp-unit framework. The system definition file is cl-threadpool-test.asd.

Run all tests

(asdf:load-system "cl-threadpool-test")
(in-package :cl-threadpool-test)
(run-tests)

Run a specific test

(asdf:load-system "cl-threadpool-test")
(in-package :cl-threadpool-test)
(run-tests '(worker-thread-p-test-1))

The thread pool has been tested on the following operating systems and Lisp implementations:

The /script directory contains a couple of shell scripts for running the test suite.

Contact

On any questions/bugs/feature requests create an issue or contact me: Oliver


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 cl-threadpool

Maintainer

Oliver <frechmatz@gmx.de>

Author

Oliver <frechmatz@gmx.de>

Home Page

https://github.com/Frechmatz/cl-threadpool

License

MIT

Description

Implementation of a thread pool

Long Description

Implementation of a thread pool

Version

1.0.0

Dependencies
Source

cl-threadpool.asd (file)

Component

src/threadpool (module)


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

3 Modules

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


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

3.1 cl-threadpool/src/threadpool

Parent

cl-threadpool (system)

Location

src/threadpool/

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 cl-threadpool.asd

Location

cl-threadpool.asd

Systems

cl-threadpool (system)


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

4.1.2 cl-threadpool/src/threadpool/packages.lisp

Parent

src/threadpool (module)

Location

src/threadpool/packages.lisp

Packages

cl-threadpool


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

4.1.3 cl-threadpool/src/threadpool/threadpool.lisp

Dependency

packages.lisp (file)

Parent

src/threadpool (module)

Location

src/threadpool/threadpool.lisp

Exported Definitions
Internal Definitions

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

5 Packages

Packages are listed by definition order.


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

5.1 cl-threadpool

Source

packages.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 Functions

Function: add-job POOL JOB

Add a job to the pool.
pool – A threadpool instance as created by make-threadpool. job – A function with zero arguments.
* The pool must have been started.
* The pool must not be in stopping state.
* The pool must not be in stopped state.

Package

cl-threadpool

Source

threadpool.lisp (file)

Function: make-threadpool SIZE &key NAME MAX-QUEUE-SIZE RESIGNAL-JOB-CONDITIONS

Create a thread pool.
name – Name of the pool.
size – Number of worker threads.
max-queue-size – The maximum number of pending jobs
resignal-job-conditions – if t then conditions signalled by the worker will be resignalled as errors

Package

cl-threadpool

Source

threadpool.lisp (file)

Function: start POOL

Start the thread pool.
pool – A thread pool instance created by make-threadpool.

Package

cl-threadpool

Source

threadpool.lisp (file)

Function: stop POOL &key FORCE-DESTROY-TIMEOUT-SECONDS

Stop the thread pool.
Returns when all threads have stopped.
pool – A threadpool instance created by make-threadpool. force-destroy-timeout-seconds – An optional timeout after all still active threads will be destroyed.
* All queued jobs will be executed.
* The stopping thread must not be a worker thread of the pool (to avoid deadlock).

Package

cl-threadpool

Source

threadpool.lisp (file)

Function: threadpoolp OBJ

Returns t if the given object represents a thread pool.

Package

cl-threadpool

Source

threadpool.lisp (file)

Function: worker-thread-p POOL

Returns true if the current thread is a worker thread of the given pool.

Package

cl-threadpool

Source

threadpool.lisp (file)


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

6.1.2 Conditions

Condition: threadpool-error ()

The default condition that is signalled by thread pools

Package

cl-threadpool

Source

threadpool.lisp (file)

Direct superclasses

error (condition)

Direct methods

text (method)

Direct slots
Slot: text
Initargs

:text

Readers

text (generic function)

Condition: threadpool-error-queue-capacity-exceeded ()

This condition is signalled when a job could not be added to the pool because the maximum number of pending jobs was reached

Package

cl-threadpool

Source

threadpool.lisp (file)

Direct superclasses

error (condition)

Direct methods

text (method)

Direct slots
Slot: text
Initargs

:text

Readers

text (generic function)


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

6.2 Internal definitions


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

6.2.1 Macros

Macro: poll (&key TIMEOUT-SECONDS) TEST-BODY TIMEOUT-BODY

Evaluates repeatedly test-body. If the test-body returns true the loop terminates. If the timeout has been reached the timeout-body is executed and the loop terminates.
timeout-seconds – the timeout in seconds or nil for no timeout. test-body – The form to be evaluated repeatedly. It is up to the test body to take care of CPU usage. The test-body is evaluated at least once.
timeout-body – The form to be evaluated when a timeout occurs.

Package

cl-threadpool

Source

threadpool.lisp (file)

Macro: signal-pool-error-if PREDICATE POOL ERROR-MESSAGE &key COND-TYPE
Package

cl-threadpool

Source

threadpool.lisp (file)

Macro: with-pool-state-lock-held POOL STATE &body BODY
Package

cl-threadpool

Source

threadpool.lisp (file)

Macro: with-threads THREADLIST THREAD &body BODY

Iterate through all non-exited threads

Package

cl-threadpool

Source

threadpool.lisp (file)


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

6.2.2 Functions

Function: add-thread THREADLIST THREAD

Add a thread. If the thread is already present then do nothing

Package

cl-threadpool

Source

threadpool.lisp (file)

Function: all-threads-stopped-p POOL

Returns t if all threads are stopped.

Package

cl-threadpool

Source

threadpool.lisp (file)

Function: destroy-all POOL

Destroy all threads that haven’t exited yet.

Package

cl-threadpool

Source

threadpool.lisp (file)

Function: generate-thread-name THREADLIST

Generate a thread name

Package

cl-threadpool

Source

threadpool.lisp (file)

Function: get-job POOL

Get a job of the job queue. Returns nil if no job is available

Package

cl-threadpool

Source

threadpool.lisp (file)

Function: make-worker-thread POOL

Adds a worker thread to the pool.

Package

cl-threadpool

Source

threadpool.lisp (file)

Function: notify-all POOL

Wake up all blocked threads.

Package

cl-threadpool

Source

threadpool.lisp (file)

Function: thread-count THREADLIST

Get number of non-exited threads

Package

cl-threadpool

Source

threadpool.lisp (file)

Function: threadlist-worker-thread-p THREADLIST THREAD

Returns true if the given thread is a worker thread of the given pool.

Package

cl-threadpool

Source

threadpool.lisp (file)


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

6.2.3 Generic functions

Generic Function: text CONDITION
Package

cl-threadpool

Methods
Method: text (CONDITION threadpool-error-queue-capacity-exceeded)
Source

threadpool.lisp (file)

Method: text (CONDITION threadpool-error)
Source

threadpool.lisp (file)


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

6.2.4 Classes

Class: threadlist ()

Instances of this class hold all threads created by the thread pool.

Package

cl-threadpool

Source

threadpool.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

initialize-instance (method)

Direct slots
Slot: lock
Initform

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

Slot: threads
Initform

(quote nil)

Slot: thread-name-prefix
Initform

"threadlist"

Class: threadpool ()
Package

cl-threadpool

Source

threadpool.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

initialize-instance (method)

Direct slots
Slot: job-queue
Initform

(queues:make-queue :simple-queue)

Slot: max-queue-size
Slot: resignal-job-conditions
Slot: threads
Initform

(make-instance (quote cl-threadpool::threadlist) :thread-name-prefix "threadpool")

Slot: size

Number of worker threads

Slot: name
Initform

"threadpool"

Slot: state

State of the thread pool.
One of nil, :RUNNING, :STOPPING, :STOPPED

Slot: state-lock
Initform

(bordeaux-threads:make-lock "thread-pool-state-lock")

Slot: cv
Initform

(bordeaux-threads:make-condition-variable)

Slot: cv-lock
Initform

(bordeaux-threads:make-lock "thread-pool-cv-lock")


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
cl-threadpool.asd: The cl-threadpool<dot>asd file
cl-threadpool/src/threadpool: The cl-threadpool/src/threadpool module
cl-threadpool/src/threadpool/packages.lisp: The cl-threadpool/src/threadpool/packages<dot>lisp file
cl-threadpool/src/threadpool/threadpool.lisp: The cl-threadpool/src/threadpool/threadpool<dot>lisp file

F
File, Lisp, cl-threadpool.asd: The cl-threadpool<dot>asd file
File, Lisp, cl-threadpool/src/threadpool/packages.lisp: The cl-threadpool/src/threadpool/packages<dot>lisp file
File, Lisp, cl-threadpool/src/threadpool/threadpool.lisp: The cl-threadpool/src/threadpool/threadpool<dot>lisp file

L
Lisp File, cl-threadpool.asd: The cl-threadpool<dot>asd file
Lisp File, cl-threadpool/src/threadpool/packages.lisp: The cl-threadpool/src/threadpool/packages<dot>lisp file
Lisp File, cl-threadpool/src/threadpool/threadpool.lisp: The cl-threadpool/src/threadpool/threadpool<dot>lisp file

M
Module, cl-threadpool/src/threadpool: The cl-threadpool/src/threadpool module

Jump to:   C   F   L   M  

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

A.2 Functions

Jump to:   A   D   F   G   M   N   P   S   T   W  
Index Entry  Section

A
add-job: Exported functions
add-thread: Internal functions
all-threads-stopped-p: Internal functions

D
destroy-all: Internal functions

F
Function, add-job: Exported functions
Function, add-thread: Internal functions
Function, all-threads-stopped-p: Internal functions
Function, destroy-all: Internal functions
Function, generate-thread-name: Internal functions
Function, get-job: Internal functions
Function, make-threadpool: Exported functions
Function, make-worker-thread: Internal functions
Function, notify-all: Internal functions
Function, start: Exported functions
Function, stop: Exported functions
Function, thread-count: Internal functions
Function, threadlist-worker-thread-p: Internal functions
Function, threadpoolp: Exported functions
Function, worker-thread-p: Exported functions

G
generate-thread-name: Internal functions
Generic Function, text: Internal generic functions
get-job: Internal functions

M
Macro, poll: Internal macros
Macro, signal-pool-error-if: Internal macros
Macro, with-pool-state-lock-held: Internal macros
Macro, with-threads: Internal macros
make-threadpool: Exported functions
make-worker-thread: Internal functions
Method, text: Internal generic functions
Method, text: Internal generic functions

N
notify-all: Internal functions

P
poll: Internal macros

S
signal-pool-error-if: Internal macros
start: Exported functions
stop: Exported functions

T
text: Internal generic functions
text: Internal generic functions
text: Internal generic functions
thread-count: Internal functions
threadlist-worker-thread-p: Internal functions
threadpoolp: Exported functions

W
with-pool-state-lock-held: Internal macros
with-threads: Internal macros
worker-thread-p: Exported functions

Jump to:   A   D   F   G   M   N   P   S   T   W  

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

A.3 Variables

Jump to:   C   J   L   M   N   R   S   T  
Index Entry  Section

C
cv: Internal classes
cv-lock: Internal classes

J
job-queue: Internal classes

L
lock: Internal classes

M
max-queue-size: Internal classes

N
name: Internal classes

R
resignal-job-conditions: Internal classes

S
size: Internal classes
Slot, cv: Internal classes
Slot, cv-lock: Internal classes
Slot, job-queue: Internal classes
Slot, lock: Internal classes
Slot, max-queue-size: Internal classes
Slot, name: Internal classes
Slot, resignal-job-conditions: Internal classes
Slot, size: Internal classes
Slot, state: Internal classes
Slot, state-lock: Internal classes
Slot, text: Exported conditions
Slot, text: Exported conditions
Slot, thread-name-prefix: Internal classes
Slot, threads: Internal classes
Slot, threads: Internal classes
state: Internal classes
state-lock: Internal classes

T
text: Exported conditions
text: Exported conditions
thread-name-prefix: Internal classes
threads: Internal classes
threads: Internal classes

Jump to:   C   J   L   M   N   R   S   T  

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

A.4 Data types

Jump to:   C   P   S   T  
Index Entry  Section

C
cl-threadpool: The cl-threadpool system
cl-threadpool: The cl-threadpool package
Class, threadlist: Internal classes
Class, threadpool: Internal classes
Condition, threadpool-error: Exported conditions
Condition, threadpool-error-queue-capacity-exceeded: Exported conditions

P
Package, cl-threadpool: The cl-threadpool package

S
System, cl-threadpool: The cl-threadpool system

T
threadlist: Internal classes
threadpool: Internal classes
threadpool-error: Exported conditions
threadpool-error-queue-capacity-exceeded: Exported conditions

Jump to:   C   P   S   T