The bordeaux-threads Reference Manual

This is the bordeaux-threads Reference Manual, version 0.8.8, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon May 15 03:26:46 2023 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 bordeaux-threads

Bordeaux Threads makes writing portable multi-threaded apps simple.

Author

Greg Pfeil <>

License

MIT

Version

0.8.8

Dependency

alexandria (system).

Source

bordeaux-threads.asd.

Child Components

3 Modules

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


3.1 bordeaux-threads/src

Source

bordeaux-threads.asd.

Parent Component

bordeaux-threads (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 bordeaux-threads/bordeaux-threads.asd

Source

bordeaux-threads.asd.

Parent Component

bordeaux-threads (system).

ASDF Systems

bordeaux-threads.


4.1.2 bordeaux-threads/src/pkgdcl.lisp

Source

bordeaux-threads.asd.

Parent Component

src (module).

Packages

bordeaux-threads.


4.1.3 bordeaux-threads/src/bordeaux-threads.lisp

Dependency

pkgdcl.lisp (file).

Source

bordeaux-threads.asd.

Parent Component

src (module).

Public Interface
Internals

4.1.4 bordeaux-threads/src/impl-sbcl.lisp

Dependency

bordeaux-threads.lisp (file).

Source

bordeaux-threads.asd.

Parent Component

src (module).

Public Interface
Internals

%make-thread (function).


4.1.5 bordeaux-threads/src/default-implementations.lisp

Dependency

impl-sbcl.lisp (file).

Source

bordeaux-threads.asd.

Parent Component

src (module).

Public Interface
Internals

4.2 Static


4.2.1 bordeaux-threads/version.sexp

Source

bordeaux-threads.asd.

Parent Component

bordeaux-threads (system).


5 Packages

Packages are listed by definition order.


5.1 bordeaux-threads

BORDEAUX-THREADS is a proposed standard for a minimal
MP/threading interface. It is similar to the CLIM-SYS threading and lock support, but for the following broad differences:

1) Some behaviours are defined in additional detail: attention has been given to special variable interaction, whether and when cleanup forms are run. Some behaviours are defined in less detail: an implementation that does not support multiple threads is not required to use a new list (nil) for a lock, for example.

2) Many functions which would be difficult, dangerous or inefficient to provide on some implementations have been removed. Chiefly these are functions such as thread-wait which expect for efficiency that the thread scheduler is written in Lisp and ’hookable’, which can’t sensibly be done if the scheduler is external to the Lisp image, or the system has more than one CPU.

3) Unbalanced ACQUIRE-LOCK and RELEASE-LOCK functions have been added.

4) Posix-style condition variables have been added, as it’s not otherwise possible to implement them correctly using the other operations that are specified.

Threads may be implemented using whatever applicable techniques are provided by the operating system: user-space scheduling, kernel-based LWPs or anything else that does the job.

Some parts of this specification can also be implemented in a Lisp that does not support multiple threads. Thread creation and some thread inspection operations will not work, but the locking functions are still present (though they may do nothing) so that thread-safe code can be compiled on both multithread and single-thread implementations without need of conditionals.

To avoid conflict with existing MP/threading interfaces in implementations, these symbols live in the BORDEAUX-THREADS package. Implementations and/or users may also make them visible or exported in other more traditionally named packages.

Source

pkgdcl.lisp.

Nickname

bt

Use List
  • alexandria.
  • 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: *default-special-bindings*

This variable holds an alist associating special variable symbols
to forms to evaluate. Special variables named in this list will
be locally bound in the new thread before it begins executing user code.

This variable may be rebound around calls to MAKE-THREAD to add/alter default bindings. The effect of mutating this list is undefined, but earlier forms take precedence over later forms for the same symbol, so defaults may be overridden by consing to the head of the list.

Package

bordeaux-threads.

Source

bordeaux-threads.lisp.

Special Variable: *standard-io-bindings*

Standard bindings of printer/reader control variables as per CL:WITH-STANDARD-IO-SYNTAX.

Package

bordeaux-threads.

Source

bordeaux-threads.lisp.

Special Variable: *supports-threads-p*

This should be set to T if the running instance has thread support.

Package

bordeaux-threads.

Source

bordeaux-threads.lisp.


6.1.2 Macros

Macro: with-lock-held ((place) &body body)

Evaluates BODY with the lock named by PLACE, the value of which
is a lock created by MAKE-LOCK. Before the forms in BODY are evaluated, the lock is acquired as if by using ACQUIRE-LOCK. After the forms in BODY have been evaluated, or if a non-local control transfer is caused (e.g. by THROW or SIGNAL), the lock is released as if by RELEASE-LOCK.

Note that if the debugger is entered, it is unspecified whether the lock is released at debugger entry or at debugger exit when execution is restarted.

Package

bordeaux-threads.

Source

impl-sbcl.lisp.

Macro: with-recursive-lock-held ((place) &body body)

Evaluates BODY with the recursive lock named by PLACE, which is a reference to a recursive lock created by MAKE-RECURSIVE-LOCK. See WITH-LOCK-HELD etc etc

Package

bordeaux-threads.

Source

impl-sbcl.lisp.

Macro: with-timeout ((timeout) &body body)
Package

bordeaux-threads.

Source

impl-sbcl.lisp.


6.1.3 Ordinary functions

Function: acquire-lock (lock &optional wait-p)

Acquire the lock LOCK for the calling thread.
WAIT-P governs what happens if the lock is not available: if WAIT-P is true, the calling thread will wait until the lock is available and then acquire it; if WAIT-P is NIL, ACQUIRE-LOCK will return immediately. ACQUIRE-LOCK returns true if the lock was acquired and NIL otherwise.

This specification does not define what happens if a thread attempts to acquire a lock that it already holds. For applications that require locks to be safe when acquired recursively, see instead MAKE-RECURSIVE-LOCK and friends.

Package

bordeaux-threads.

Source

impl-sbcl.lisp.

Function: acquire-recursive-lock (lock)

As for ACQUIRE-LOCK, but for recursive locks.

Package

bordeaux-threads.

Source

default-implementations.lisp.

Function: all-threads ()

Returns a sequence of all of the threads. This may not be freshly-allocated, so the caller should not modify it.

Package

bordeaux-threads.

Source

impl-sbcl.lisp.

Function: condition-notify (condition-variable)

Notify at least one of the threads waiting for CONDITION-VARIABLE. It is implementation-dependent whether one or more than one (and possibly all) threads are woken, but if the implementation is capable of waking only a single thread (not all are) this is probably preferable for efficiency reasons. The order of wakeup is unspecified and does not necessarily relate to the order that the threads went to sleep in.

CONDITION-NOTIFY has no useful return value. In an implementation that does not support multiple threads, it has no effect.

Package

bordeaux-threads.

Source

impl-sbcl.lisp.

Function: condition-wait (condition-variable lock &key timeout)

Atomically release LOCK and enqueue the calling
thread waiting for CONDITION-VARIABLE. The thread will resume when another thread has notified it using CONDITION-NOTIFY; it may also resume if interrupted by some external event or in other implementation-dependent circumstances: the caller must always test on waking that there is threading to be done, instead of assuming that it can go ahead.

It is an error to call function this unless from the thread that holds LOCK.

If TIMEOUT is nil or not provided, the system always reacquires LOCK before returning to the caller. In this case T is returned.

If TIMEOUT is non-nil, the call will return after at most TIMEOUT seconds (approximately), whether or not a notification has occurred. Either NIL or T will be returned. A return of NIL indicates that the lock is no longer held and that the timeout has expired. A return of T indicates that the lock is held, in which case the timeout may or may not have expired.

**NOTE**: The behavior of CONDITION-WAIT with TIMEOUT diverges from the POSIX function pthread_cond_timedwait. The former may return without the lock being held while the latter always returns with the lock held.

In an implementation that does not support multiple threads, this function signals an error.

Package

bordeaux-threads.

Source

impl-sbcl.lisp.

Function: current-thread ()

Returns the thread object for the calling
thread. This is the same kind of object as would be returned by MAKE-THREAD.

Package

bordeaux-threads.

Source

impl-sbcl.lisp.

Function: destroy-thread (thread)

Terminates the thread THREAD, which is an object
as returned by MAKE-THREAD. This should be used with caution: it is implementation-defined whether the thread runs cleanup forms or releases its locks first.

Destroying the calling thread is an error.

Package

bordeaux-threads.

Source

impl-sbcl.lisp.

Function: interrupt-thread (thread function &rest args)

Interrupt THREAD and cause it to evaluate FUNCTION
before continuing with the interrupted path of execution. This may not be a good idea if THREAD is holding locks or doing anything important. On systems that do not support multiple threads, this function signals an error.

Package

bordeaux-threads.

Source

impl-sbcl.lisp.

Function: join-thread (thread)

Wait until THREAD terminates. If THREAD has already terminated, return immediately. The return values of the thread function are returned.

Package

bordeaux-threads.

Source

impl-sbcl.lisp.

Function: lock-p (object)

Returns T if OBJECT is a lock; returns NIL otherwise.

Package

bordeaux-threads.

Source

impl-sbcl.lisp.

Function: make-condition-variable (&key name)

Returns a new condition-variable object for use with CONDITION-WAIT and CONDITION-NOTIFY.

Package

bordeaux-threads.

Source

impl-sbcl.lisp.

Function: make-lock (&optional name)

Creates a lock (a mutex) whose name is NAME. If the system does not support multiple threads this will still return some object, but it may not be used for very much.

Package

bordeaux-threads.

Source

impl-sbcl.lisp.

Function: make-recursive-lock (&optional name)

Create and return a recursive lock whose name is NAME. A recursive lock differs from an ordinary lock in that a thread that already holds the recursive lock can acquire it again without blocking. The thread must then release the lock twice before it becomes available for another thread.

Package

bordeaux-threads.

Source

impl-sbcl.lisp.

Function: make-semaphore (&key name count)

Create a semaphore with the supplied NAME and initial counter value COUNT.

Package

bordeaux-threads.

Source

impl-sbcl.lisp.

Function: make-thread (function &key name initial-bindings)

Creates and returns a thread named NAME, which will call the function FUNCTION with no arguments: when FUNCTION returns, the thread terminates. NAME defaults to "Anonymous thread" if unsupplied.

On systems that do not support multi-threading, MAKE-THREAD will signal an error.

The interaction between threads and dynamic variables is in some cases complex, and depends on whether the variable has only a global binding (as established by e.g. DEFVAR/DEFPARAMETER/top-level SETQ) or has been bound locally (e.g. with LET or LET*) in the calling thread.

- Global bindings are shared between threads: the initial value of a global variable in the new thread will be the same as in the parent, and an assignment to such a variable in any thread will be visible to all threads in which the global binding is visible.

- Local bindings, such as the ones introduced by INITIAL-BINDINGS, are local to the thread they are introduced in, except that

- Local bindings in the the caller of MAKE-THREAD may or may not be shared with the new thread that it creates: this is implementation-defined. Portable code should not depend on particular behaviour in this case, nor should it assign to such variables without first rebinding them in the new thread.

Package

bordeaux-threads.

Source

default-implementations.lisp.

Function: recursive-lock-p (object)

Returns T if OBJECT is a recursive lock; returns NIL otherwise.

Package

bordeaux-threads.

Source

impl-sbcl.lisp.

Function: release-lock (lock)

Release LOCK. It is an error to call this unless
the lock has previously been acquired (and not released) by the same thread. If other threads are waiting for the lock, the ACQUIRE-LOCK call in one of them will now be able to continue.

This function has no interesting return value.

Package

bordeaux-threads.

Source

impl-sbcl.lisp.

Function: release-recursive-lock (lock)

Release the recursive LOCK. The lock will only
become free after as many Release operations as there have been Acquire operations. See RELEASE-LOCK for other information.

Package

bordeaux-threads.

Source

default-implementations.lisp.

Function: semaphore-p (object)

Returns T if OBJECT is a semaphore; returns NIL otherwise.

Package

bordeaux-threads.

Source

default-implementations.lisp.

Function: signal-semaphore (semaphore &key count)

Increment SEMAPHORE by COUNT. If there are threads waiting on this semaphore, then COUNT of them are woken up.

Package

bordeaux-threads.

Source

impl-sbcl.lisp.

Function: start-multiprocessing ()

If the host implementation uses user-level threads, start the scheduler and multiprocessing, otherwise do nothing.
It is safe to call repeatedly.

Package

bordeaux-threads.

Source

default-implementations.lisp.

Function: thread-alive-p (thread)

Returns true if THREAD is alive, that is, if DESTROY-THREAD has not been called on it.

Package

bordeaux-threads.

Source

impl-sbcl.lisp.

Function: thread-name (thread)

Returns the name of the thread, as supplied to MAKE-THREAD.

Package

bordeaux-threads.

Source

impl-sbcl.lisp.

Function: thread-yield ()

Allows other threads to run. It may be necessary or desirable to call this periodically in some implementations; others may schedule threads automatically. On systems that do not support multi-threading, this does nothing.

Package

bordeaux-threads.

Source

impl-sbcl.lisp.

Function: threadp (object)

Returns true if object is a thread, otherwise NIL.

Package

bordeaux-threads.

Source

impl-sbcl.lisp.

Function: wait-on-semaphore (semaphore &key timeout)

Decrement the count of SEMAPHORE by 1 if the count would not be negative.

Else blocks until the semaphore can be decremented. Returns generalized boolean T on success.

If TIMEOUT is given, it is the maximum number of seconds to wait. If the count cannot be decremented in that time, returns NIL without decrementing the count.

Package

bordeaux-threads.

Source

impl-sbcl.lisp.


6.1.4 Types

Type: lock ()
Package

bordeaux-threads.

Source

impl-sbcl.lisp.

Type: recursive-lock ()
Package

bordeaux-threads.

Source

impl-sbcl.lisp.

Type: semaphore ()
Package

bordeaux-threads.

Source

impl-sbcl.lisp.

Type: thread ()
Package

bordeaux-threads.

Source

impl-sbcl.lisp.

Type: timeout ()
Package

bordeaux-threads.

Source

impl-sbcl.lisp.


6.2 Internals


6.2.1 Special variables

Special Variable: *no-condition-wait-timeout-message*
Package

bordeaux-threads.

Source

bordeaux-threads.lisp.


6.2.2 Macros

Macro: defbindings (name docstring &body initforms)
Package

bordeaux-threads.

Source

bordeaux-threads.lisp.

Macro: defdfun (name args doc &body body)
Package

bordeaux-threads.

Source

default-implementations.lisp.

Macro: defdmacro (name args doc &body body)
Package

bordeaux-threads.

Source

default-implementations.lisp.

Macro: define-condition-wait-compiler-macro ()
Package

bordeaux-threads.

Source

bordeaux-threads.lisp.


6.2.3 Ordinary functions

Function: %make-thread (function name)

The actual implementation-dependent function that creates threads.

Package

bordeaux-threads.

Source

impl-sbcl.lisp.

Reader: %semaphore-condition-variable (instance)
Writer: (setf %semaphore-condition-variable) (instance)
Package

bordeaux-threads.

Source

bordeaux-threads.lisp.

Target Slot

condition-variable.

Reader: %semaphore-counter (instance)
Writer: (setf %semaphore-counter) (instance)
Package

bordeaux-threads.

Source

bordeaux-threads.lisp.

Target Slot

counter.

Reader: %semaphore-lock (instance)
Writer: (setf %semaphore-lock) (instance)
Package

bordeaux-threads.

Source

bordeaux-threads.lisp.

Target Slot

lock.

Function: %semaphore-p (object)
Package

bordeaux-threads.

Source

bordeaux-threads.lisp.

Function: binding-default-specials (function special-bindings)

Return a closure that binds the symbols in SPECIAL-BINDINGS and calls FUNCTION.

Package

bordeaux-threads.

Source

bordeaux-threads.lisp.

Function: copy-%semaphore (instance)
Package

bordeaux-threads.

Source

bordeaux-threads.lisp.

Function: make-%semaphore (&key lock condition-variable counter)
Package

bordeaux-threads.

Source

bordeaux-threads.lisp.

Function: mark-supported ()
Package

bordeaux-threads.

Source

bordeaux-threads.lisp.

Function: signal-error-if-condition-wait-timeout (timeout)
Package

bordeaux-threads.

Source

bordeaux-threads.lisp.

Function: signal-error-if-current-thread (thread)
Package

bordeaux-threads.

Source

bordeaux-threads.lisp.


6.2.4 Generic functions

Generic Function: make-threading-support-error ()

Creates a BORDEAUX-THREADS condition which specifies
whether there is no BORDEAUX-THREADS support for the implementation, no threads enabled for the system, or no support for a particular function.

Package

bordeaux-threads.

Source

bordeaux-threads.lisp.

Methods
Method: make-threading-support-error ()
Generic Reader: message (condition)
Package

bordeaux-threads.

Methods
Reader Method: message ((condition bordeaux-mp-condition))
Source

bordeaux-threads.lisp.

Target Slot

message.


6.2.5 Conditions

Condition: bordeaux-mp-condition
Package

bordeaux-threads.

Source

bordeaux-threads.lisp.

Direct superclasses

error.

Direct methods

message.

Direct slots
Slot: message
Initargs

:message

Readers

message.

Writers

This slot is read-only.


6.2.6 Structures

Structure: %semaphore
Package

bordeaux-threads.

Source

bordeaux-threads.lisp.

Direct superclasses

structure-object.

Direct slots
Slot: lock
Readers

%semaphore-lock.

Writers

(setf %semaphore-lock).

Slot: condition-variable
Readers

%semaphore-condition-variable.

Writers

(setf %semaphore-condition-variable).

Slot: counter
Readers

%semaphore-counter.

Writers

(setf %semaphore-counter).


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   %   (  
A   B   C   D   F   G   I   J   L   M   R   S   T   W  
Index Entry  Section

%
%make-thread: Private ordinary functions
%semaphore-condition-variable: Private ordinary functions
%semaphore-counter: Private ordinary functions
%semaphore-lock: Private ordinary functions
%semaphore-p: Private ordinary functions

(
(setf %semaphore-condition-variable): Private ordinary functions
(setf %semaphore-counter): Private ordinary functions
(setf %semaphore-lock): Private ordinary functions

A
acquire-lock: Public ordinary functions
acquire-recursive-lock: Public ordinary functions
all-threads: Public ordinary functions

B
binding-default-specials: Private ordinary functions

C
condition-notify: Public ordinary functions
condition-wait: Public ordinary functions
copy-%semaphore: Private ordinary functions
current-thread: Public ordinary functions

D
defbindings: Private macros
defdfun: Private macros
defdmacro: Private macros
define-condition-wait-compiler-macro: Private macros
destroy-thread: Public ordinary functions

F
Function, %make-thread: Private ordinary functions
Function, %semaphore-condition-variable: Private ordinary functions
Function, %semaphore-counter: Private ordinary functions
Function, %semaphore-lock: Private ordinary functions
Function, %semaphore-p: Private ordinary functions
Function, (setf %semaphore-condition-variable): Private ordinary functions
Function, (setf %semaphore-counter): Private ordinary functions
Function, (setf %semaphore-lock): Private ordinary functions
Function, acquire-lock: Public ordinary functions
Function, acquire-recursive-lock: Public ordinary functions
Function, all-threads: Public ordinary functions
Function, binding-default-specials: Private ordinary functions
Function, condition-notify: Public ordinary functions
Function, condition-wait: Public ordinary functions
Function, copy-%semaphore: Private ordinary functions
Function, current-thread: Public ordinary functions
Function, destroy-thread: Public ordinary functions
Function, interrupt-thread: Public ordinary functions
Function, join-thread: Public ordinary functions
Function, lock-p: Public ordinary functions
Function, make-%semaphore: Private ordinary functions
Function, make-condition-variable: Public ordinary functions
Function, make-lock: Public ordinary functions
Function, make-recursive-lock: Public ordinary functions
Function, make-semaphore: Public ordinary functions
Function, make-thread: Public ordinary functions
Function, mark-supported: Private ordinary functions
Function, recursive-lock-p: Public ordinary functions
Function, release-lock: Public ordinary functions
Function, release-recursive-lock: Public ordinary functions
Function, semaphore-p: Public ordinary functions
Function, signal-error-if-condition-wait-timeout: Private ordinary functions
Function, signal-error-if-current-thread: Private ordinary functions
Function, signal-semaphore: Public ordinary functions
Function, start-multiprocessing: Public ordinary functions
Function, thread-alive-p: Public ordinary functions
Function, thread-name: Public ordinary functions
Function, thread-yield: Public ordinary functions
Function, threadp: Public ordinary functions
Function, wait-on-semaphore: Public ordinary functions

G
Generic Function, make-threading-support-error: Private generic functions
Generic Function, message: Private generic functions

I
interrupt-thread: Public ordinary functions

J
join-thread: Public ordinary functions

L
lock-p: Public ordinary functions

M
Macro, defbindings: Private macros
Macro, defdfun: Private macros
Macro, defdmacro: Private macros
Macro, define-condition-wait-compiler-macro: Private macros
Macro, with-lock-held: Public macros
Macro, with-recursive-lock-held: Public macros
Macro, with-timeout: Public macros
make-%semaphore: Private ordinary functions
make-condition-variable: Public ordinary functions
make-lock: Public ordinary functions
make-recursive-lock: Public ordinary functions
make-semaphore: Public ordinary functions
make-thread: Public ordinary functions
make-threading-support-error: Private generic functions
make-threading-support-error: Private generic functions
mark-supported: Private ordinary functions
message: Private generic functions
message: Private generic functions
Method, make-threading-support-error: Private generic functions
Method, message: Private generic functions

R
recursive-lock-p: Public ordinary functions
release-lock: Public ordinary functions
release-recursive-lock: Public ordinary functions

S
semaphore-p: Public ordinary functions
signal-error-if-condition-wait-timeout: Private ordinary functions
signal-error-if-current-thread: Private ordinary functions
signal-semaphore: Public ordinary functions
start-multiprocessing: Public ordinary functions

T
thread-alive-p: Public ordinary functions
thread-name: Public ordinary functions
thread-yield: Public ordinary functions
threadp: Public ordinary functions

W
wait-on-semaphore: Public ordinary functions
with-lock-held: Public macros
with-recursive-lock-held: Public macros
with-timeout: Public macros


A.4 Data types

Jump to:   %  
B   C   D   F   I   L   M   P   R   S   T   V  
Index Entry  Section

%
%semaphore: Private structures

B
bordeaux-mp-condition: Private conditions
bordeaux-threads: The bordeaux-threads system
bordeaux-threads: The bordeaux-threads package
bordeaux-threads.asd: The bordeaux-threads/bordeaux-threads․asd file
bordeaux-threads.lisp: The bordeaux-threads/src/bordeaux-threads․lisp file

C
Condition, bordeaux-mp-condition: Private conditions

D
default-implementations.lisp: The bordeaux-threads/src/default-implementations․lisp file

F
File, bordeaux-threads.asd: The bordeaux-threads/bordeaux-threads․asd file
File, bordeaux-threads.lisp: The bordeaux-threads/src/bordeaux-threads․lisp file
File, default-implementations.lisp: The bordeaux-threads/src/default-implementations․lisp file
File, impl-sbcl.lisp: The bordeaux-threads/src/impl-sbcl․lisp file
File, pkgdcl.lisp: The bordeaux-threads/src/pkgdcl․lisp file
File, version.sexp: The bordeaux-threads/version․sexp file

I
impl-sbcl.lisp: The bordeaux-threads/src/impl-sbcl․lisp file

L
lock: Public types

M
Module, src: The bordeaux-threads/src module

P
Package, bordeaux-threads: The bordeaux-threads package
pkgdcl.lisp: The bordeaux-threads/src/pkgdcl․lisp file

R
recursive-lock: Public types

S
semaphore: Public types
src: The bordeaux-threads/src module
Structure, %semaphore: Private structures
System, bordeaux-threads: The bordeaux-threads system

T
thread: Public types
timeout: Public types
Type, lock: Public types
Type, recursive-lock: Public types
Type, semaphore: Public types
Type, thread: Public types
Type, timeout: Public types

V
version.sexp: The bordeaux-threads/version․sexp file