The cl-threadpool Reference Manual

This is the cl-threadpool Reference Manual, version 3.0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 15:47:10 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 cl-threadpool

Implementation of a thread pool

Maintainer

Oliver <>

Author

Oliver <>

Home Page

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

License

MIT

Long Description

Implementation of a thread pool

Version

3.0.1

Dependencies
  • bordeaux-threads (system).
  • queues.simple-cqueue (system).
Source

cl-threadpool.asd.

Child Component

src/threadpool (module).


3 Modules

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


3.1 cl-threadpool/src/threadpool

Source

cl-threadpool.asd.

Parent Component

cl-threadpool (system).

Child Components

4 Files

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


4.1 Lisp


4.1.1 cl-threadpool/cl-threadpool.asd

Source

cl-threadpool.asd.

Parent Component

cl-threadpool (system).

ASDF Systems

cl-threadpool.


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

Source

cl-threadpool.asd.

Parent Component

src/threadpool (module).

Packages

cl-threadpool.


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

Dependency

packages.lisp (file).

Source

cl-threadpool.asd.

Parent Component

src/threadpool (module).

Public Interface
Internals

5 Packages

Packages are listed by definition order.


5.1 cl-threadpool

Source

packages.lisp.

Use List

common-lisp.

Public Interface
Internals

6 Definitions

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


6.1 Public Interface


6.1.1 Special variables

Special Variable: *logger*

The logger of cl-threadpool. The default implementation is empty.
Refer to test/util/logger.lisp for an implementation using the "verbose" library.

Package

cl-threadpool.

Source

threadpool.lisp.


6.1.2 Ordinary functions

Function: add-job (pool job)

Adds a job to the pool. The function has the following arguments: <ul>
<li>pool A thread pool.</li>
<li>job A function with no arguments.</li>
</ul>
Returns a future.

Package

cl-threadpool.

Source

threadpool.lisp.

Function: cancel-job (future)

Cancels a job. The function does nothing when the job is already done.

Package

cl-threadpool.

Source

threadpool.lisp.

Function: job-cancelled-p (future)

Returns t if the job has been cancelled.

Package

cl-threadpool.

Source

threadpool.lisp.

Function: job-done-p (future)

Returns t if the job is done. A job is done when it has succesfully completed, signalled a condition or has been cancelled.

Package

cl-threadpool.

Source

threadpool.lisp.

Function: job-execution-error-message (job-execution-error)

Returns the error message of the given job execution error.

Package

cl-threadpool.

Source

threadpool.lisp.

Function: job-execution-error-pool-name (job-execution-error)

Returns the name of the thread pool that has signalled the given job execution error.

Package

cl-threadpool.

Source

threadpool.lisp.

Function: job-result (future)

Get the result of a job. If the result is already available it will immediately be returned. Otherwise the function blocks on the completion of the job. The function may signal one of the following conditions:
<ul>
<li>job-execution-error The job has signalled a condition.</li> <li>job-cancellation-error The job has been cancelled.</li>
</ul>

Package

cl-threadpool.

Source

threadpool.lisp.

Function: make-threadpool (size &key name)

Instantiates a thread pool. The function has the following arguments: <ul>
<li>size Number of worker threads.</li>
<li>:name Name of the pool.</li>
</ul>
Returns a thread pool.

Package

cl-threadpool.

Source

threadpool.lisp.

Function: pool-name (pool)

Returns the name of the pool.

Package

cl-threadpool.

Source

threadpool.lisp.

Function: pool-stopped-p (pool)

Returns t if the job queue of the pool is empty and all worker threads have ended.

Package

cl-threadpool.

Source

threadpool.lisp.

Function: queue-size (pool)

Returns the current length of the job queue.

Package

cl-threadpool.

Source

threadpool.lisp.

Function: run-jobs (pool jobs)

Executes a batch of jobs and returns their results. Blocks until
all jobs are done. The function has the following arguments:
<ul>
<li>pool A thread pool</li>
<li>jobs A list of jobs. Each job is represented by a function with no arguments.</li> </ul>
May signal one of the following conditions:
<ul>
<li>job-execution-error When a job has signalled a condition.</li> <li>job-cancellation-error When a job has been cancelled.</li>
</ul>
Returns an ordered list of job results.

Package

cl-threadpool.

Source

threadpool.lisp.

Function: stop (pool &key timeout-seconds)

<p>Stops all worker threads. The function returns when all worker threads are no longer alive or when the timeout has been reached or when the pool is stopping or is already stopped. All pending jobs that are not currently being executed by a worker thread will be cancelled by one of the worker threads.</p>
<p>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.</p>
<p>See also pool-stopped-p to check if the pool has successfully been stopped.</p>

Package

cl-threadpool.

Source

threadpool.lisp.

Function: threadpoolp (obj)

Returns t if the given object represents a thread pool.

Package

cl-threadpool.

Source

threadpool.lisp.

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.


6.1.3 Conditions

Condition: job-cancellation-error

This condition is signalled when the result of a job is requested but the job has been cancelled.

Package

cl-threadpool.

Source

threadpool.lisp.

Direct superclasses

error.

Condition: job-execution-error

This condition is signalled when the result of a job is requested but the job has signalled a condition during its execution.

Package

cl-threadpool.

Source

threadpool.lisp.

Direct superclasses

error.

Direct slots
Slot: pool-name
Initargs

:pool-name

Slot: thread-id
Initargs

:thread-id

Slot: message
Initargs

:message


6.2 Internals


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.


6.2.2 Ordinary functions

Function: add-job-impl (pool job)
Package

cl-threadpool.

Source

threadpool.lisp.

Function: assert-futurep (obj)
Package

cl-threadpool.

Source

threadpool.lisp.

Function: assert-jobp (job)
Package

cl-threadpool.

Source

threadpool.lisp.

Function: assert-threadpoolp (obj)
Package

cl-threadpool.

Source

threadpool.lisp.

Function: complete-job (future value)

Sets the value of a successfully completed job. If the future
has already been cancelled the value is ignored and the future remains cancelled. If the future is already completed but not cancelled the function signals an error. The function has the following arguments:
<ul>
<li>future The future.</li>
<li>value The value.</li>
</ul>

Package

cl-threadpool.

Source

threadpool.lisp.

Function: future-state-cancelled-p (future-state)
Package

cl-threadpool.

Source

threadpool.lisp.

Function: future-state-done-p (future-state)
Package

cl-threadpool.

Source

threadpool.lisp.

Function: futurep (obj)

Returns t if the given object represents a future.

Package

cl-threadpool.

Source

threadpool.lisp.

Function: job-execution-error-thread-id (job-execution-error)

Returns the id of the thread that has signalled the given job execution error.

Package

cl-threadpool.

Source

threadpool.lisp.

Function: log-error (format-control &rest format-arguments)
Package

cl-threadpool.

Source

threadpool.lisp.

Function: log-info (format-control &rest format-arguments)
Package

cl-threadpool.

Source

threadpool.lisp.

Function: log-trace (format-control &rest format-arguments)
Package

cl-threadpool.

Source

threadpool.lisp.

Function: make-worker-thread (pool thread-id)
Package

cl-threadpool.

Source

threadpool.lisp.

Function: pool-state-stopped-p (pool-state)
Package

cl-threadpool.

Source

threadpool.lisp.

Function: pool-state-stopping-p (pool-state)
Package

cl-threadpool.

Source

threadpool.lisp.

Function: queue-size-no-lock (pool)
Package

cl-threadpool.

Source

threadpool.lisp.

Function: reject-job (future pool-name thread-id message)

Sets a job to rejected. This happens when a job signals an unhandled condition. Does nothing when the future is cancelled. Signals an error when the future has already completed or rejected.
The function has the following arguments:
<ul>
<li>future The future.</li>
<li>pool-name Name of the pool.</li>
<li>thread-id Id of the worker thread.</li>
<li>message A message.</li>
</ul>

Package

cl-threadpool.

Source

threadpool.lisp.


6.2.3 Generic functions

Generic Function: get-future (future-factory)

Get a future. Returns an available future or creates a new one.

Package

cl-threadpool.

Source

threadpool.lisp.

Methods
Method: get-future ((future-factory-instance future-factory))
Generic Function: put-future (future-factory future)

Put back a previously requested future into the pool. Putting back
a future can only happen when the ownership of the future is well
defined. For example when the threadpool is asked to synchronously run
a batch of jobs then the underlying futures are not exposed to the application and can safely be put back for further re-use.

Package

cl-threadpool.

Source

threadpool.lisp.

Methods
Method: put-future ((future-factory-instance future-factory) future)

6.2.4 Classes

Class: future

A Future represents the result of a job. Futures provide functions
to get the result of a job, to check if the job has been completed or cancelled and to cancel a job.

Package

cl-threadpool.

Source

threadpool.lisp.

Direct slots
Slot: lock
Initform

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

Slot: cv
Initform

(bordeaux-threads:make-condition-variable)

Slot: state
Initform

:pending

Slot: job

Function to be invoked by a worker thread.

Slot: value
Class: future-factory

Creates future instances and keeps a pool of futures that can be re-used.

Package

cl-threadpool.

Source

threadpool.lisp.

Direct methods
Direct slots
Slot: lock
Initform

(bordeaux-threads:make-lock "future-factory-lock")

Slot: pool
Slot: created-future-count

For debugging/testing purposes.

Initform

0

Class: threadpool
Package

cl-threadpool.

Source

threadpool.lisp.

Direct slots
Slot: job-queue

Pending jobs. Jobs are represented by instances of future.

Initform

(queues:make-queue :simple-queue)

Slot: future-factory
Initform

(make-instance (quote cl-threadpool::future-factory))

Slot: threads
Slot: size

Number of worker threads

Initargs

:size

Slot: name
Initform

(format nil "threadpool-~a" (gensym))

Initargs

:name

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)


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   A   C   F   G   J   L   M   P   Q   R   S   T   W  
Index Entry  Section

A
add-job: Public ordinary functions
add-job-impl: Private ordinary functions
assert-futurep: Private ordinary functions
assert-jobp: Private ordinary functions
assert-threadpoolp: Private ordinary functions

C
cancel-job: Public ordinary functions
complete-job: Private ordinary functions

F
Function, add-job: Public ordinary functions
Function, add-job-impl: Private ordinary functions
Function, assert-futurep: Private ordinary functions
Function, assert-jobp: Private ordinary functions
Function, assert-threadpoolp: Private ordinary functions
Function, cancel-job: Public ordinary functions
Function, complete-job: Private ordinary functions
Function, future-state-cancelled-p: Private ordinary functions
Function, future-state-done-p: Private ordinary functions
Function, futurep: Private ordinary functions
Function, job-cancelled-p: Public ordinary functions
Function, job-done-p: Public ordinary functions
Function, job-execution-error-message: Public ordinary functions
Function, job-execution-error-pool-name: Public ordinary functions
Function, job-execution-error-thread-id: Private ordinary functions
Function, job-result: Public ordinary functions
Function, log-error: Private ordinary functions
Function, log-info: Private ordinary functions
Function, log-trace: Private ordinary functions
Function, make-threadpool: Public ordinary functions
Function, make-worker-thread: Private ordinary functions
Function, pool-name: Public ordinary functions
Function, pool-state-stopped-p: Private ordinary functions
Function, pool-state-stopping-p: Private ordinary functions
Function, pool-stopped-p: Public ordinary functions
Function, queue-size: Public ordinary functions
Function, queue-size-no-lock: Private ordinary functions
Function, reject-job: Private ordinary functions
Function, run-jobs: Public ordinary functions
Function, stop: Public ordinary functions
Function, threadpoolp: Public ordinary functions
Function, worker-thread-p: Public ordinary functions
future-state-cancelled-p: Private ordinary functions
future-state-done-p: Private ordinary functions
futurep: Private ordinary functions

G
Generic Function, get-future: Private generic functions
Generic Function, put-future: Private generic functions
get-future: Private generic functions
get-future: Private generic functions

J
job-cancelled-p: Public ordinary functions
job-done-p: Public ordinary functions
job-execution-error-message: Public ordinary functions
job-execution-error-pool-name: Public ordinary functions
job-execution-error-thread-id: Private ordinary functions
job-result: Public ordinary functions

L
log-error: Private ordinary functions
log-info: Private ordinary functions
log-trace: Private ordinary functions

M
Macro, poll: Private macros
make-threadpool: Public ordinary functions
make-worker-thread: Private ordinary functions
Method, get-future: Private generic functions
Method, put-future: Private generic functions

P
poll: Private macros
pool-name: Public ordinary functions
pool-state-stopped-p: Private ordinary functions
pool-state-stopping-p: Private ordinary functions
pool-stopped-p: Public ordinary functions
put-future: Private generic functions
put-future: Private generic functions

Q
queue-size: Public ordinary functions
queue-size-no-lock: Private ordinary functions

R
reject-job: Private ordinary functions
run-jobs: Public ordinary functions

S
stop: Public ordinary functions

T
threadpoolp: Public ordinary functions

W
worker-thread-p: Public ordinary functions