API Reference

Every exported symbol of the cl-threads package. Every function has a docstring; (documentation 'th:parallel-for 'function) gives it at the REPL.

Job pools

make-job-pool function

(make-job-pool &key (workers (default-worker-count)) (name "cl-threads worker")
                    (on-error :signal) error-handler bindings)
  → job-pool

Starts a pool of workers worker threads, named name and their index. on-error is :signal or :debug. error-handler, a function of the condition or nil, is the default handler of the groups the pool makes. bindings, ((symbol value) ...), are bound in every worker. See Job Pools and Errors in Jobs.

destroy-job-pool function

(destroy-job-pool pool)

Finishes the pool's jobs, then stops the workers and waits for them. From the moment it is called, the pool takes no jobs from other threads, but runs every job queued or running and the jobs they queue. Signals threads-error from one of the pool's own workers. Does nothing on a pool being or already destroyed.

with-job-pool macro

(with-job-pool (pool &rest options) body ...)

Binds pool to a pool made with options, as make-job-pool takes them, evaluates the body, and destroys the pool however the body is left.

job-pool class

A pool of worker threads. Any thread may give it work and wait for it.

Function	Returns
(job-pool-worker-count pool)	The number of workers.
(default-worker-count)	The number of workers a pool has by default: processors minus two, at least 1. The processors are counted on Linux and Windows; elsewhere it is 1.
(worker-index)	The calling worker's index in its pool, or nil outside workers. Allocates nothing.

Running jobs

parallel-for function

(parallel-for pool start end function &key chunk-size)

Calls (function chunk-start chunk-end) on the workers for each chunk of the integers from start below end, and returns when all have returned. Chunks hold chunk-size integers, by default enough for four per worker. Signals job-error if a chunk signalled an error. From a worker of pool, runs chunks itself while it waits. Allocates nothing in steady state. See Parallel For.

job-group structure

Jobs counted together. Any thread may submit to it; one thread at a time waits for it. Reusable once its jobs are done.

make-job-group function

(make-job-group pool &key (error-handler <the pool's>)) → job-group

A new, empty group of pool. error-handler, a function of the condition or nil, gets the group's jobs' errors as they happen; with nil, they are kept for wait-for-jobs.

submit-job function

(submit-job group function) → group

Runs function, with no arguments, on a worker, counted in group. Returns group at once.

submit-parallel-for function

(submit-parallel-for group start end function &key chunk-size) → group

Queues the chunks of the range as parallel-for does, counted in group, and returns group at once. Allocates nothing in steady state on a reused group.

jobs-done-p function

(jobs-done-p group) → boolean

True if every job submitted to group has finished. Never waits; allocates nothing.

wait-for-jobs function

(wait-for-jobs group)

Waits until the group's jobs have finished; a worker of the pool runs the group's queued jobs meanwhile, and no others. Signals job-error if one signalled an error and the group has no error handler. See Job Groups.

Worker storage

worker-local structure

A value for each worker of a pool. Each value belongs to its worker.

make-worker-local function

(make-worker-local pool function) → worker-local

Calls function with each worker's index, now, in this thread, and keeps the results.

worker-local-value function

(worker-local-value local) → value

The calling worker's value. Signals threads-error outside the pool's workers. Allocates nothing.

worker-local-values function

(worker-local-values local) → list

Every worker's value, in order of index. See Worker Storage.

Threads

Function	Description
(make-thread function &key name bindings on-error) → thread	Starts a thread that calls function with no arguments. name is a string, "cl-threads thread" by default. bindings, ((symbol value) ...), are bound in the thread for its whole life; otherwise it sees the global values of special variables. on-error says what an error the function does not handle does: :debug, the default, opens the debugger in the thread; :signal unwinds the function, and join-thread signals a thread-error carrying the error. Signals threads-error for bindings that are not such a list, or that bind a constant.
(join-thread thread) → values	Waits until the thread has ended, its function having returned or been unwound, and returns the function's values, or none if it was unwound. Signals thread-error if an error unwound it, in a thread made with :on-error :signal. Any number of joins, from any threads, and each gets the same. Signals threads-error when joining the calling thread or a thread not made by make-thread.
(current-thread) → thread	The calling thread, in any thread: from its first instruction in one made by make-thread; in any other, a thread made on first call and returned ever after, which cannot be joined. Allocates nothing after the first call.
(thread-name thread) → string	The name it was made with, or the implementation's name for a thread not made by make-thread.
(thread-finished-p thread) → boolean	True once the thread has ended: for one made by make-thread, a moment after its function has returned or been unwound. True after a join.
(interrupt-thread thread function) → boolean	Makes thread call function, with no arguments, as soon as it can, in the middle of what it is doing, and returns at once; the thread then goes on where it was. True if the interrupt was sent, nil if the thread had finished. Any thread, the caller too. Never leave function by a non-local exit: it may run inside a foreign call.

thread is a structure type. See Threads and Synchronisation.

Locks

Name	Description
lock	type. A mutual exclusion lock. Not recursive.
(make-lock &optional name) → lock	A new lock; name is a string, "cl-threads lock" by default.
(with-lock (lock) body ...)	macro. Evaluates the body holding the lock, and releases it however the body is left. Allocates nothing.

Semaphores

Name	Description
semaphore	type. A counting semaphore.
(make-semaphore &key (count 0)) → semaphore	A new semaphore with a count of count.
(signal-semaphore semaphore &optional (count 1))	Raises the count by count, a non-negative integer, waking up to that many waiting threads. Returns no values.
(wait-on-semaphore semaphore &key timeout) → boolean	Waits until the count is above 0 and lowers it. With timeout, a non-negative real in seconds, gives up after that long. True if it lowered the count, nil if it timed out.

Conditions and restarts

Name	Description
threads-error	condition, an error. The base of every error cl-threads signals. threads-error-message gives what went wrong and what to do about it.
job-error	condition, a threads-error. Signalled by parallel-for and wait-for-jobs when a job failed. job-error-condition gives the job's own error.
thread-error	condition, a threads-error. Signalled by join-thread when the function of a thread made with :on-error :signal ended in an error. thread-error-condition gives that error, and thread-error-thread the thread.
retry-job	restart, in :on-error :debug pools: runs the failed job again. Also (retry-job &optional condition), a function that invokes it, or returns nil if there is none.
skip-job	restart, in :on-error :debug pools: skips the failed job. Also (skip-job &optional condition), a function that invokes it, or returns nil if there is none.

See Errors in Jobs.