The pcall Reference Manual

Table of Contents

The pcall Reference Manual

This is the pcall Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Feb 19 21:18:06 2020 GMT+0.

1 Systems

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

1.1 pcall

Dependencies

• bordeaux-threads
• pcall-queue (system)

Source

pcall.asd (file)

Components

• package.lisp (file)
• task.lisp (file)
• pool.lisp (file)
• pcall.lisp (file)

1.2 pcall-queue

Dependency

bordeaux-threads

Source

pcall-queue.asd (file)

Component

queue.lisp (file)

2 Files

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

2.1 Lisp

2.1.1 pcall.asd

Location

pcall.asd

Systems

pcall (system)

2.1.2 pcall-queue.asd

Location

pcall-queue.asd

Systems

pcall-queue (system)

2.1.3 pcall/package.lisp

Parent

pcall (system)

Location

package.lisp

Packages

pcall

2.1.4 pcall/task.lisp

Dependency

package.lisp (file)

Parent

pcall (system)

Location

task.lisp

Exported Definitions

• done-p (function)
• join (function)
• select-one (function)

Internal Definitions

• execute-task (function)
• task (class)
• task-error (method)
• (setf task-error) (method)
• task-lock (method)
• task-status (method)
• (setf task-status) (method)
• task-thunk (method)
• task-values (method)
• (setf task-values) (method)
• task-wait-locks (method)
• (setf task-wait-locks) (method)
• task-waiting (method)
• (setf task-waiting) (method)
• with-locks (function)

2.1.5 pcall/pool.lisp

Dependency

task.lisp (file)

Parent

pcall (system)

Location

pool.lisp

Exported Definitions

• finish-tasks (function)
• set-worker-environment (function)
• thread-pool-size (function)
• (setf thread-pool-size) (function)
• with-local-thread-pool (macro)

Internal Definitions

• *pool* (special variable)
• audit-thread-pool (function)
• copy-pool (function)
• make-pool (function)
• pool (structure)
• pool-env (function)
• (setf pool-env) (function)
• pool-lock (function)
• (setf pool-lock) (function)
• pool-p (function)
• pool-queue (function)
• (setf pool-queue) (function)
• pool-size (function)
• (setf pool-size) (function)
• pool-threads (function)
• (setf pool-threads) (function)
• spawn-thread (function)
• stop-at-once-p (method)
• stop-running (condition)
• stop-thread (function)
• worker-thread (function)

2.1.6 pcall/pcall.lisp

Dependencies

• task.lisp (file)
• pool.lisp (file)

Parent

pcall (system)

Location

pcall.lisp

Exported Definitions

• pcall (function)
• pexec (macro)
• plet (macro)

2.1.7 pcall-queue/queue.lisp

Parent

pcall-queue (system)

Location

queue.lisp

Packages

pcall-queue

Exported Definitions

• make-queue (function)
• queue-empty-p (function)
• queue-length (function)
• queue-pop (function)
• queue-push (function)
• queue-wait (function)

Internal Definitions

• copy-node (function)
• make-node (function)
• node (structure)
• node-next (function)
• (setf node-next) (function)
• node-p (function)
• node-prev (function)
• (setf node-prev) (function)
• node-val (function)
• (setf node-val) (function)
• queue (class)
• queue-back (method)
• (setf queue-back) (method)
• queue-condition (method)
• queue-do-pop (function)
• queue-front (method)
• (setf queue-front) (method)
• queue-lock (method)

3 Packages

Packages are listed by definition order.

3.1 pcall

Source

package.lisp (file)

Use List

• pcall-queue
• bordeaux-threads
• common-lisp

Exported Definitions

• done-p (function)
• finish-tasks (function)
• join (function)
• pcall (function)
• pexec (macro)
• plet (macro)
• select-one (function)
• set-worker-environment (function)
• thread-pool-size (function)
• (setf thread-pool-size) (function)
• with-local-thread-pool (macro)

Internal Definitions

• *pool* (special variable)
• audit-thread-pool (function)
• copy-pool (function)
• execute-task (function)
• make-pool (function)
• pool (structure)
• pool-env (function)
• (setf pool-env) (function)
• pool-lock (function)
• (setf pool-lock) (function)
• pool-p (function)
• pool-queue (function)
• (setf pool-queue) (function)
• pool-size (function)
• (setf pool-size) (function)
• pool-threads (function)
• (setf pool-threads) (function)
• spawn-thread (function)
• stop-at-once-p (generic function)
• stop-at-once-p (method)
• stop-running (condition)
• stop-thread (function)
• task (class)
• task-error (generic function)
• task-error (method)
• (setf task-error) (method)
• (setf task-error) (generic function)
• task-lock (generic function)
• task-lock (method)
• task-status (generic function)
• task-status (method)
• (setf task-status) (method)
• (setf task-status) (generic function)
• task-thunk (generic function)
• task-thunk (method)
• task-values (generic function)
• task-values (method)
• (setf task-values) (method)
• (setf task-values) (generic function)
• task-wait-locks (generic function)
• task-wait-locks (method)
• (setf task-wait-locks) (method)
• (setf task-wait-locks) (generic function)
• task-waiting (generic function)
• task-waiting (method)
• (setf task-waiting) (method)
• (setf task-waiting) (generic function)
• with-locks (function)
• worker-thread (function)

3.2 pcall-queue

Source

queue.lisp (file)

Use List

• bordeaux-threads
• common-lisp

Used By List

pcall

Exported Definitions

• make-queue (function)
• queue-empty-p (function)
• queue-length (function)
• queue-pop (function)
• queue-push (function)
• queue-wait (function)

Internal Definitions

• copy-node (function)
• make-node (function)
• node (structure)
• node-next (function)
• (setf node-next) (function)
• node-p (function)
• node-prev (function)
• (setf node-prev) (function)
• node-val (function)
• (setf node-val) (function)
• queue (class)
• queue-back (generic function)
• queue-back (method)
• (setf queue-back) (method)
• (setf queue-back) (generic function)
• queue-condition (generic function)
• queue-condition (method)
• queue-do-pop (function)
• queue-front (generic function)
• queue-front (method)
• (setf queue-front) (method)
• (setf queue-front) (generic function)
• queue-lock (generic function)
• queue-lock (method)

4 Definitions

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

4.1 Exported definitions

4.1.1 Macros

Macro: pexec &body BODY

Shorthand for pcall.

Package

pcall

Source

pcall.lisp (file)

Macro: plet (&rest BINDINGS) &body BODY

Package

pcall

Source

pcall.lisp (file)

Macro: with-local-thread-pool (&key SIZE ON-UNWIND WORKER-ENVIRONMENT) &body BODY

Run body with a fresh thread pool. If on-unwind is :wait, it will wait for all tasks to finish before returning. If it is :leave, the form will return while threads are still working. If it is :stop or :destroy, the threads will be stopped at the end of the body. With :stop, they will first finish their current task (if any), with :destroy, they will be brutally destroyed and might leak resources, leave stuff in inconsistent state, etc.

Package

pcall

Source

pool.lisp (file)

4.1.2 Functions

Function: done-p TASK

Package

pcall

Source

task.lisp (file)

Function: finish-tasks ()

Package

pcall

Source

pool.lisp (file)

Function: join TASK

Join a task, meaning stop execution of the current thread until the result of the task is available, and then return this result. When this is called on a task that no thread is currently working on, the current thread executes the task directly.

Package

pcall

Source

task.lisp (file)

Function: make-queue ()

Create an empty queue.

Package

pcall-queue

Source

queue.lisp (file)

Function: pcall THUNK

Call a thunk in parallel. Returns a task that can be joined. When an exclusive is given, the task will only run when no other tasks with that exclusive are running.

Package

pcall

Source

pcall.lisp (file)

Function: queue-empty-p QUEUE

Test whether a queue is empty.

Package

pcall-queue

Source

queue.lisp (file)

Function: queue-length QUEUE

Find the length of a queue.

Package

pcall-queue

Source

queue.lisp (file)

Function: queue-pop QUEUE

Pop an element from the front of a queue. Returns immediately, returning nil if the queue is empty, and a second value indicating whether anything was popped.

Package

pcall-queue

Source

queue.lisp (file)

Function: queue-push ELT QUEUE

Push an element onto the back of a queue.

Package

pcall-queue

Source

queue.lisp (file)

Function: queue-wait QUEUE

Pop an element from the front of a queue. Causes a blocking wait when no elements are available.

Package

pcall-queue

Source

queue.lisp (file)

Function: select-one &rest TASKS

Returns the first task that can be joined without blocking.

Package

pcall

Source

task.lisp (file)

Function: set-worker-environment WRAPPER

Package

pcall

Source

pool.lisp (file)

Function: thread-pool-size ()

Function: (setf thread-pool-size) SIZE

Package

pcall

Source

pool.lisp (file)

4.2 Internal definitions

4.2.1 Special variables

Special Variable: *pool*

Package

pcall

Source

pool.lisp (file)

4.2.2 Functions

Function: audit-thread-pool ()

Make sure the thread pool holds the correct amount of live threads.

Package

pcall

Source

pool.lisp (file)

Function: copy-node INSTANCE

Package

pcall-queue

Source

queue.lisp (file)

Function: copy-pool INSTANCE

Package

pcall

Source

pool.lisp (file)

Function: execute-task TASK

Execute a task, and store the result or error in the task object. When a task’s status is not :free, that means the joiner has already started executing it, so this thread should leave it alone.

Package

pcall

Source

task.lisp (file)

Function: make-node &key (VAL VAL) (NEXT NEXT) (PREV PREV)

Package

pcall-queue

Source

queue.lisp (file)

Function: make-pool &key (THREADS THREADS) (SIZE SIZE) (LOCK LOCK) (ENV ENV) (QUEUE QUEUE)

Package

pcall

Source

pool.lisp (file)

Function: node-next INSTANCE

Function: (setf node-next) VALUE INSTANCE

Package

pcall-queue

Source

queue.lisp (file)

Function: node-p OBJECT

Package

pcall-queue

Source

queue.lisp (file)

Function: node-prev INSTANCE

Function: (setf node-prev) VALUE INSTANCE

Package

pcall-queue

Source

queue.lisp (file)

Function: node-val INSTANCE

Function: (setf node-val) VALUE INSTANCE

Package

pcall-queue

Source

queue.lisp (file)

Function: pool-env INSTANCE

Function: (setf pool-env) VALUE INSTANCE

Package

pcall

Source

pool.lisp (file)

Function: pool-lock INSTANCE

Function: (setf pool-lock) VALUE INSTANCE

Package

pcall

Source

pool.lisp (file)

Function: pool-p OBJECT

Package

pcall

Source

pool.lisp (file)

Function: pool-queue INSTANCE

Function: (setf pool-queue) VALUE INSTANCE

Package

pcall

Source

pool.lisp (file)

Function: pool-size INSTANCE

Function: (setf pool-size) VALUE INSTANCE

Package

pcall

Source

pool.lisp (file)

Function: pool-threads INSTANCE

Function: (setf pool-threads) VALUE INSTANCE

Package

pcall

Source

pool.lisp (file)

Function: queue-do-pop QUEUE

Package

pcall-queue

Source

queue.lisp (file)

Function: spawn-thread POOL

Package

pcall

Source

pool.lisp (file)

Function: stop-thread THREAD AT-ONCE-P

Package

pcall

Source

pool.lisp (file)

Function: with-locks LOCKS THUNK

Package

pcall

Source

task.lisp (file)

Function: worker-thread QUEUE

The code running inside the pooled threads. Repeatedly tries to take a task from the queue, and handles it.

Package

pcall

Source

pool.lisp (file)

4.2.3 Generic functions

Generic Function: queue-back OBJECT

Generic Function: (setf queue-back) NEW-VALUE OBJECT

Package

pcall-queue

Methods

Method: queue-back (QUEUE queue)

automatically generated reader method

Source

queue.lisp (file)

Method: (setf queue-back) NEW-VALUE (QUEUE queue)

automatically generated writer method

Source

queue.lisp (file)

Generic Function: queue-condition OBJECT

Package

pcall-queue

Methods

Method: queue-condition (QUEUE queue)

automatically generated reader method

Source

queue.lisp (file)

Generic Function: queue-front OBJECT

Generic Function: (setf queue-front) NEW-VALUE OBJECT

Package

pcall-queue

Methods

Method: queue-front (QUEUE queue)

automatically generated reader method

Source

queue.lisp (file)

Method: (setf queue-front) NEW-VALUE (QUEUE queue)

automatically generated writer method

Source

queue.lisp (file)

Generic Function: queue-lock OBJECT

Package

pcall-queue

Methods

Method: queue-lock (QUEUE queue)

automatically generated reader method

Source

queue.lisp (file)

Generic Function: stop-at-once-p CONDITION

Package

pcall

Methods

Method: stop-at-once-p (CONDITION stop-running)

Source

pool.lisp (file)

Generic Function: task-error OBJECT

Generic Function: (setf task-error) NEW-VALUE OBJECT

Package

pcall

Methods

Method: task-error (TASK task)

automatically generated reader method

Source

task.lisp (file)

Method: (setf task-error) NEW-VALUE (TASK task)

automatically generated writer method

Source

task.lisp (file)

Generic Function: task-lock OBJECT

Package

pcall

Methods

Method: task-lock (TASK task)

automatically generated reader method

Source

task.lisp (file)

Generic Function: task-status OBJECT

Generic Function: (setf task-status) NEW-VALUE OBJECT

Package

pcall

Methods

Method: task-status (TASK task)

automatically generated reader method

Source

task.lisp (file)

Method: (setf task-status) NEW-VALUE (TASK task)

automatically generated writer method

Source

task.lisp (file)

Generic Function: task-thunk OBJECT

Package

pcall

Methods

Method: task-thunk (TASK task)

automatically generated reader method

Source

task.lisp (file)

Generic Function: task-values OBJECT

Generic Function: (setf task-values) NEW-VALUE OBJECT

Package

pcall

Methods

Method: task-values (TASK task)

automatically generated reader method

Source

task.lisp (file)

Method: (setf task-values) NEW-VALUE (TASK task)

automatically generated writer method

Source

task.lisp (file)

Generic Function: task-wait-locks OBJECT

Generic Function: (setf task-wait-locks) NEW-VALUE OBJECT

Package

pcall

Methods

Method: task-wait-locks (TASK task)

automatically generated reader method

Source

task.lisp (file)

Method: (setf task-wait-locks) NEW-VALUE (TASK task)

automatically generated writer method

Source

task.lisp (file)

Generic Function: task-waiting OBJECT

Generic Function: (setf task-waiting) NEW-VALUE OBJECT

Package

pcall

Methods

Method: task-waiting (TASK task)

automatically generated reader method

Source

task.lisp (file)

Method: (setf task-waiting) NEW-VALUE (TASK task)

automatically generated writer method

Source

task.lisp (file)

4.2.4 Conditions

Condition: stop-running ()

Package

pcall

Source

pool.lisp (file)

Direct superclasses

condition (condition)

Direct methods

stop-at-once-p (method)

Direct slots

Slot: at-once-p

Initargs

:at-once-p

Readers

stop-at-once-p (generic function)

4.2.5 Structures

Structure: node ()

Package

pcall-queue

Source

queue.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots

Slot: val

Readers

node-val (function)

Writers

(setf node-val) (function)

Slot: next

Readers

node-next (function)

Writers

(setf node-next) (function)

Slot: prev

Readers

node-prev (function)

Writers

(setf node-prev) (function)

Structure: pool ()

Package

pcall

Source

pool.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots

Slot: threads

Readers

pool-threads (function)

Writers

(setf pool-threads) (function)

Slot: size

Initform

3

Readers

pool-size (function)

Writers

(setf pool-size) (function)

Slot: lock

Initform

(bordeaux-threads:make-lock)

Readers

pool-lock (function)

Writers

(setf pool-lock) (function)

Slot: env

Readers

pool-env (function)

Writers

(setf pool-env) (function)

Slot: queue

Initform

(pcall-queue:make-queue)

Readers

pool-queue (function)

Writers

(setf pool-queue) (function)

4.2.6 Classes

Class: queue ()

Package

pcall-queue

Source

queue.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• queue-back (method)
• queue-back (method)
• queue-front (method)
• queue-front (method)
• queue-condition (method)
• queue-lock (method)

Direct slots

Slot: lock

Initform

(bordeaux-threads:make-lock)

Readers

queue-lock (generic function)

Slot: condition

Initform

(bordeaux-threads:make-condition-variable)

Readers

queue-condition (generic function)

Slot: front

Readers

queue-front (generic function)

Writers

(setf queue-front) (generic function)

Slot: back

Readers

queue-back (generic function)

Writers

(setf queue-back) (generic function)

Class: task ()

A task is a piece of code that is scheduled to run in the thread pool.

Package

pcall

Source

task.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• task-waiting (method)
• task-waiting (method)
• task-status (method)
• task-status (method)
• task-wait-locks (method)
• task-wait-locks (method)
• task-lock (method)
• task-values (method)
• task-values (method)
• task-error (method)
• task-error (method)
• task-thunk (method)

Direct slots

Slot: thunk

Initargs

:thunk

Readers

task-thunk (generic function)

Slot: error

Readers

task-error (generic function)

Writers

(setf task-error) (generic function)

Slot: values

Readers

task-values (generic function)

Writers

(setf task-values) (generic function)

Slot: lock

Initform

(bordeaux-threads:make-lock)

Readers

task-lock (generic function)

Slot: wait-locks

Readers

task-wait-locks (generic function)

Writers

(setf task-wait-locks) (generic function)

Slot: status

Initform

:free

Readers

task-status (generic function)

Writers

(setf task-status) (generic function)

Slot: waiting

Readers

task-waiting (generic function)

Writers

(setf task-waiting) (generic function)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types