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 2.0.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Fri Jun 26 10:38:26 2020 GMT+0.


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

1 Introduction

cl-threadpool

A thread pool implemented in Common Lisp.

A thread pool consists of a bunch of worker threads and a job queue. The library provides an easy to use API with a focus on blocking execution of job batches.

Change-Log

Version 1.0.0

Initial release of cl-threadpool.

Version 2.0.0

This version is the current quicklisp release.

Version 2 is a major rework of the thread pool with bugfixes, new features and removal of features that have been identified as not being useful.

Breaking changes

New features

Installation

Install (downloads and installs all dependencies)

(ql:quickload "cl-threadpool")

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 thread pool.

(cl-threadpool:start *threadpool*)

Run a batch of jobs. Blocks the current thread until all jobs have finished.

(let ((results
       (cl-threadpool:run-jobs
        *threadpool*
        (list
         (lambda() (sleep 5) "Job 1")
         (lambda() (sleep 2) "Job 2")
         (lambda() (sleep 1) "Job 3")))))
  (format t "~a" (first results)) ;; => "Job 1"
  (format t "~a" (second results)) ;; => "Job 2"
  (format t "~a" (third results)))) ;; => "Job 3"

Stop the thread pool.

(cl-threadpool:stop *threadpool*)

API

Logging

The thread pool logs low-level events by calling the function cl-threadpool:*logger* The default implementation of this function is empty.

Running the tests

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

Supported Lisp implementations and operating systems

cl-threadpool has been tested with:

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

2.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 Special variables

Special Variable: *logger*
Package

cl-threadpool

Source

threadpool.lisp (file)


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

6.1.2 Functions

Function: make-threadpool SIZE &key NAME

Create a thread pool.
name – Name of the pool. size – Number of worker threads.

Package

cl-threadpool

Source

threadpool.lisp (file)

Function: pool-name POOL

Get the name of the pool.

Package

cl-threadpool

Source

threadpool.lisp (file)

Function: queue-size POOL

Get the current length of the job queue.

Package

cl-threadpool

Source

threadpool.lisp (file)

Function: run-jobs POOL JOBS

Synchronously run a list of jobs and return their results. Blocks the current thread until all jobs have been completed. Jobs are supposed to handle all conditions.
- pool: The threadpool
- jobs: A list of jobs. Each job is represented by a function with no arguments. Returns an ordered list of the results that the jobs have returned.

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 TIMEOUT-SECONDS

Stops all worker threads. The function returns when all worker threads are no longer alive or when the timeout has been reached. Jobs still sitting in the queue may not be executed. The function does not destroy threads but signals to the worker threads that they are supposed to end. If a worker thread refuses to end it will be left running.
Returns nil when all worker threads have been be stopped.

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.3 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)


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. If test-body returns t then the pool loop quits. timeout-body – The form to be evaluated when a timeout occurs.

Package

cl-threadpool

Source

threadpool.lisp (file)


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

6.2.2 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. A job is supposed to handle all conditions. * 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: assert-jobp JOB
Package

cl-threadpool

Source

threadpool.lisp (file)

Function: assert-threadpoolp OBJ
Package

cl-threadpool

Source

threadpool.lisp (file)

Function: log-info FORMAT-CONTROL &rest FORMAT-ARGUMENTS
Package

cl-threadpool

Source

threadpool.lisp (file)

Function: log-trace FORMAT-CONTROL &rest FORMAT-ARGUMENTS
Package

cl-threadpool

Source

threadpool.lisp (file)

Function: make-job-lock-pool ()

Creates a pool that manages job locks.
Returns a property list with the following keys:
- :get A function that allocates a job lock. If there is no lock available
a new one will be created. Locks returned by this function are supposed to be put back into the pool.
- :put A function that puts back a previously allocated job lock into the pool.
A job lock is represented by a property list with the following keys:
- :set-value A function with one argument that sets the result of a job.
- :get-value A function that returns the result of a job. If the result is
already available it will immediately be returned. Otherwise the function
blocks on the execution of the job.

Package

cl-threadpool

Source

threadpool.lisp (file)

Function: make-worker-thread POOL THREAD-ID
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)
Source

threadpool.lisp (file)


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

6.2.4 Classes

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: job-lock-pool
Initform

(cl-threadpool::make-job-lock-pool)

Slot: threads
Slot: size

Number of worker threads

Slot: name
Initform

"threadpool"

Slot: state

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

Initform

:pending

Slot: lock
Initform

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

Slot: cv
Initform

(bordeaux-threads:make-condition-variable)


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

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

L
Lisp File, cl-threadpool.asd: The cl-threadpool․asd file
Lisp File, cl-threadpool/src/threadpool/packages.lisp: The cl-threadpool/src/threadpool/packages․lisp file
Lisp File, cl-threadpool/src/threadpool/threadpool.lisp: The cl-threadpool/src/threadpool/threadpool․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   F   G   L   M   P   Q   R   S   T   W  
Index Entry  Section

A
add-job: Internal functions
assert-jobp: Internal functions
assert-threadpoolp: Internal functions

F
Function, add-job: Internal functions
Function, assert-jobp: Internal functions
Function, assert-threadpoolp: Internal functions
Function, log-info: Internal functions
Function, log-trace: Internal functions
Function, make-job-lock-pool: Internal functions
Function, make-threadpool: Exported functions
Function, make-worker-thread: Internal functions
Function, pool-name: Exported functions
Function, queue-size: Exported functions
Function, run-jobs: Exported functions
Function, start: Exported functions
Function, stop: Exported functions
Function, threadpoolp: Exported functions
Function, worker-thread-p: Exported functions

G
Generic Function, text: Internal generic functions

L
log-info: Internal functions
log-trace: Internal functions

M
Macro, poll: Internal macros
make-job-lock-pool: Internal functions
make-threadpool: Exported functions
make-worker-thread: Internal functions
Method, text: Internal generic functions

P
poll: Internal macros
pool-name: Exported functions

Q
queue-size: Exported functions

R
run-jobs: Exported functions

S
start: Exported functions
stop: Exported functions

T
text: Internal generic functions
text: Internal generic functions
threadpoolp: Exported functions

W
worker-thread-p: Exported functions

Jump to:   A   F   G   L   M   P   Q   R   S   T   W  

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

A.3 Variables

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

*
*logger*: Exported special variables

C
cv: Internal classes

J
job-lock-pool: Internal classes
job-queue: Internal classes

L
lock: Internal classes

N
name: Internal classes

S
size: Internal classes
Slot, cv: Internal classes
Slot, job-lock-pool: Internal classes
Slot, job-queue: Internal classes
Slot, lock: Internal classes
Slot, name: Internal classes
Slot, size: Internal classes
Slot, state: Internal classes
Slot, text: Exported conditions
Slot, threads: Internal classes
Special Variable, *logger*: Exported special variables
state: Internal classes

T
text: Exported conditions
threads: Internal classes

Jump to:   *  
C   J   L   N   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, threadpool: Internal classes
Condition, threadpool-error: Exported conditions

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

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

T
threadpool: Internal classes
threadpool-error: Exported conditions

Jump to:   C   P   S   T