The bordeaux-threads Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The bordeaux-threads Reference Manual

This is the bordeaux-threads Reference Manual, version 0.8.5, generated automatically by Declt version 2.3 "Robert April" on Tue Jan 09 13:14:31 2018 GMT+0.


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

1 Introduction

You can find API documentation on the project's wiki:
	http://trac.common-lisp.net/bordeaux-threads/wiki/ApiDocumentation


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 bordeaux-threads

Author

Greg Pfeil <greg@technomadic.org>

License

MIT

Description

Bordeaux Threads makes writing portable multi-threaded apps simple.

Version

0.8.5

Dependency

alexandria

Source

bordeaux-threads.asd (file)

Component

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

Parent

bordeaux-threads (system)

Location

src/

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

Location

bordeaux-threads.asd

Systems

bordeaux-threads (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.2 bordeaux-threads/src/pkgdcl.lisp

Parent

src (module)

Location

src/pkgdcl.lisp

Packages

bordeaux-threads


Next: , Previous: , Up: Lisp files   [Contents][Index]

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

Dependency

pkgdcl.lisp (file)

Parent

src (module)

Location

src/bordeaux-threads.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

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

Dependency

bordeaux-threads.lisp (file)

Parent

src (module)

Location

src/impl-sbcl.lisp

Exported Definitions
Internal Definitions

%make-thread (function)


Previous: , Up: Lisp files   [Contents][Index]

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

Dependency

impl-sbcl.lisp (file)

Parent

src (module)

Location

src/default-implementations.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 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 (file)

Nickname

bt

Use List
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: *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 (file)

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 (file)

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 (file)


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

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 (file)

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 (file)

Macro: with-timeout (TIMEOUT) &body BODY

Execute ‘BODY’ and signal a condition of type TIMEOUT if the execution of BODY does not complete within ‘TIMEOUT’ seconds. On implementations which do not support WITH-TIMEOUT natively and don’t support threads either it has no effect.

Package

bordeaux-threads

Source

impl-sbcl.lisp (file)


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

6.1.3 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 (file)

Function: acquire-recursive-lock LOCK

As for ACQUIRE-LOCK, but for recursive locks.

Package

bordeaux-threads

Source

default-implementations.lisp (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

Function: join-thread THREAD

Wait until THREAD terminates. If THREAD has already terminated, return immediately.

Package

bordeaux-threads

Source

impl-sbcl.lisp (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

Function: thread-name THREAD

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

Package

bordeaux-threads

Source

impl-sbcl.lisp (file)

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 (file)

Function: threadp OBJECT

Returns true if object is a thread, otherwise NIL.

Package

bordeaux-threads

Source

impl-sbcl.lisp (file)


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

6.1.4 Types

Type: thread ()
Package

bordeaux-threads

Source

impl-sbcl.lisp (file)

Type: timeout ()
Package

bordeaux-threads

Source

impl-sbcl.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

6.2 Internal definitions


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

6.2.1 Special variables

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

bordeaux-threads

Source

bordeaux-threads.lisp (file)


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

6.2.2 Macros

Macro: defbindings NAME DOCSTRING &body INITFORMS
Package

bordeaux-threads

Source

bordeaux-threads.lisp (file)

Macro: defdfun NAME ARGS DOC &body BODY
Package

bordeaux-threads

Source

default-implementations.lisp (file)

Macro: defdmacro NAME ARGS DOC &body BODY
Package

bordeaux-threads

Source

default-implementations.lisp (file)

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

bordeaux-threads

Source

bordeaux-threads.lisp (file)


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

6.2.3 Functions

Function: %make-thread FUNCTION NAME

The actual implementation-dependent function that creates threads.

Package

bordeaux-threads

Source

impl-sbcl.lisp (file)

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 (file)

Function: mark-supported ()
Package

bordeaux-threads

Source

bordeaux-threads.lisp (file)

Function: signal-error-if-condition-wait-timeout TIMEOUT
Package

bordeaux-threads

Source

bordeaux-threads.lisp (file)

Function: signal-error-if-current-thread THREAD
Package

bordeaux-threads

Source

bordeaux-threads.lisp (file)


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

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 (file)

Methods
Method: make-threading-support-error ()
Generic Function: message CONDITION
Package

bordeaux-threads

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

bordeaux-threads.lisp (file)


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

6.2.5 Conditions

Condition: bordeaux-mp-condition ()
Package

bordeaux-threads

Source

bordeaux-threads.lisp (file)

Direct superclasses

error (condition)

Direct methods

message (method)

Direct slots
Slot: message
Initargs

:message

Readers

message (generic function)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   B   F   L   M  
Index Entry  Section

B
bordeaux-threads.asd: The bordeaux-threads<dot>asd file
bordeaux-threads/src: The bordeaux-threads/src module
bordeaux-threads/src/bordeaux-threads.lisp: The bordeaux-threads/src/bordeaux-threads<dot>lisp file
bordeaux-threads/src/default-implementations.lisp: The bordeaux-threads/src/default-implementations<dot>lisp file
bordeaux-threads/src/impl-sbcl.lisp: The bordeaux-threads/src/impl-sbcl<dot>lisp file
bordeaux-threads/src/pkgdcl.lisp: The bordeaux-threads/src/pkgdcl<dot>lisp file

F
File, Lisp, bordeaux-threads.asd: The bordeaux-threads<dot>asd file
File, Lisp, bordeaux-threads/src/bordeaux-threads.lisp: The bordeaux-threads/src/bordeaux-threads<dot>lisp file
File, Lisp, bordeaux-threads/src/default-implementations.lisp: The bordeaux-threads/src/default-implementations<dot>lisp file
File, Lisp, bordeaux-threads/src/impl-sbcl.lisp: The bordeaux-threads/src/impl-sbcl<dot>lisp file
File, Lisp, bordeaux-threads/src/pkgdcl.lisp: The bordeaux-threads/src/pkgdcl<dot>lisp file

L
Lisp File, bordeaux-threads.asd: The bordeaux-threads<dot>asd file
Lisp File, bordeaux-threads/src/bordeaux-threads.lisp: The bordeaux-threads/src/bordeaux-threads<dot>lisp file
Lisp File, bordeaux-threads/src/default-implementations.lisp: The bordeaux-threads/src/default-implementations<dot>lisp file
Lisp File, bordeaux-threads/src/impl-sbcl.lisp: The bordeaux-threads/src/impl-sbcl<dot>lisp file
Lisp File, bordeaux-threads/src/pkgdcl.lisp: The bordeaux-threads/src/pkgdcl<dot>lisp file

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

Jump to:   B   F   L   M  

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

A.2 Functions

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

%
%make-thread: Internal functions

A
acquire-lock: Exported functions
acquire-recursive-lock: Exported functions
all-threads: Exported functions

B
binding-default-specials: Internal functions

C
condition-notify: Exported functions
condition-wait: Exported functions
current-thread: Exported functions

D
defbindings: Internal macros
defdfun: Internal macros
defdmacro: Internal macros
define-condition-wait-compiler-macro: Internal macros
destroy-thread: Exported functions

F
Function, %make-thread: Internal functions
Function, acquire-lock: Exported functions
Function, acquire-recursive-lock: Exported functions
Function, all-threads: Exported functions
Function, binding-default-specials: Internal functions
Function, condition-notify: Exported functions
Function, condition-wait: Exported functions
Function, current-thread: Exported functions
Function, destroy-thread: Exported functions
Function, interrupt-thread: Exported functions
Function, join-thread: Exported functions
Function, make-condition-variable: Exported functions
Function, make-lock: Exported functions
Function, make-recursive-lock: Exported functions
Function, make-thread: Exported functions
Function, mark-supported: Internal functions
Function, release-lock: Exported functions
Function, release-recursive-lock: Exported functions
Function, signal-error-if-condition-wait-timeout: Internal functions
Function, signal-error-if-current-thread: Internal functions
Function, start-multiprocessing: Exported functions
Function, thread-alive-p: Exported functions
Function, thread-name: Exported functions
Function, thread-yield: Exported functions
Function, threadp: Exported functions

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

I
interrupt-thread: Exported functions

J
join-thread: Exported functions

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

R
release-lock: Exported functions
release-recursive-lock: Exported functions

S
signal-error-if-condition-wait-timeout: Internal functions
signal-error-if-current-thread: Internal functions
start-multiprocessing: Exported functions

T
thread-alive-p: Exported functions
thread-name: Exported functions
thread-yield: Exported functions
threadp: Exported functions

W
with-lock-held: Exported macros
with-recursive-lock-held: Exported macros
with-timeout: Exported macros

Jump to:   %  
A   B   C   D   F   G   I   J   M   R   S   T   W  

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

A.3 Variables

Jump to:   *  
M   S  
Index Entry  Section

*
*default-special-bindings*: Exported special variables
*no-condition-wait-timeout-message*: Internal special variables
*standard-io-bindings*: Exported special variables
*supports-threads-p*: Exported special variables

M
message: Internal conditions

S
Slot, message: Internal conditions
Special Variable, *default-special-bindings*: Exported special variables
Special Variable, *no-condition-wait-timeout-message*: Internal special variables
Special Variable, *standard-io-bindings*: Exported special variables
Special Variable, *supports-threads-p*: Exported special variables

Jump to:   *  
M   S  

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

A.4 Data types

Jump to:   B   C   P   S   T  
Index Entry  Section

B
bordeaux-mp-condition: Internal conditions
bordeaux-threads: The bordeaux-threads system
bordeaux-threads: The bordeaux-threads package

C
Condition, bordeaux-mp-condition: Internal conditions

P
Package, bordeaux-threads: The bordeaux-threads package

S
System, bordeaux-threads: The bordeaux-threads system

T
thread: Exported types
timeout: Exported types
Type, thread: Exported types
Type, timeout: Exported types

Jump to:   B   C   P   S   T