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.
The main system appears first, followed by any subsystem dependency.
bordeaux-threadsBordeaux Threads makes writing portable multi-threaded apps simple.
Greg Pfeil <greg@technomadic.org>
MIT
0.8.8
alexandria (system).
version.sexp (file).
src (module).
Modules are listed depth-first from the system components tree.
bordeaux-threads/srcbordeaux-threads (system).
pkgdcl.lisp (file).
bordeaux-threads.lisp (file).
impl-sbcl.lisp (file).
default-implementations.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
bordeaux-threads/bordeaux-threads.asdbordeaux-threads/src/pkgdcl.lispbordeaux-threads/src/bordeaux-threads.lispbordeaux-threads/src/impl-sbcl.lispbordeaux-threads/src/default-implementations.lispbordeaux-threads/bordeaux-threads.asdbordeaux-threads (system).
bordeaux-threads/src/bordeaux-threads.lisppkgdcl.lisp (file).
src (module).
*default-special-bindings* (special variable).
*standard-io-bindings* (special variable).
*supports-threads-p* (special variable).
%semaphore (structure).
%semaphore-condition-variable (reader).
(setf %semaphore-condition-variable) (writer).
%semaphore-counter (reader).
(setf %semaphore-counter) (writer).
%semaphore-lock (reader).
(setf %semaphore-lock) (writer).
%semaphore-p (function).
*no-condition-wait-timeout-message* (special variable).
binding-default-specials (function).
bordeaux-mp-condition (condition).
copy-%semaphore (function).
defbindings (macro).
define-condition-wait-compiler-macro (macro).
make-%semaphore (function).
make-threading-support-error (generic function).
mark-supported (function).
message (reader method).
signal-error-if-condition-wait-timeout (function).
signal-error-if-current-thread (function).
bordeaux-threads/src/impl-sbcl.lispbordeaux-threads.lisp (file).
src (module).
acquire-lock (function).
all-threads (function).
condition-notify (function).
condition-wait (function).
current-thread (function).
destroy-thread (function).
interrupt-thread (function).
join-thread (function).
lock (type).
lock-p (function).
make-condition-variable (function).
make-lock (function).
make-recursive-lock (function).
make-semaphore (function).
recursive-lock (type).
recursive-lock-p (function).
release-lock (function).
semaphore (type).
signal-semaphore (function).
thread (type).
thread-alive-p (function).
thread-name (function).
thread-yield (function).
threadp (function).
timeout (type).
wait-on-semaphore (function).
with-lock-held (macro).
with-recursive-lock-held (macro).
with-timeout (macro).
%make-thread (function).
bordeaux-threads/src/default-implementations.lispimpl-sbcl.lisp (file).
src (module).
acquire-recursive-lock (function).
make-thread (function).
release-recursive-lock (function).
semaphore-p (function).
start-multiprocessing (function).
Packages are listed by definition order.
bordeaux-threadsBORDEAUX-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.
bt
alexandria.
common-lisp.
*default-special-bindings* (special variable).
*standard-io-bindings* (special variable).
*supports-threads-p* (special variable).
acquire-lock (function).
acquire-recursive-lock (function).
all-threads (function).
condition-notify (function).
condition-wait (function).
current-thread (function).
destroy-thread (function).
interrupt-thread (function).
join-thread (function).
lock (type).
lock-p (function).
make-condition-variable (function).
make-lock (function).
make-recursive-lock (function).
make-semaphore (function).
make-thread (function).
recursive-lock (type).
recursive-lock-p (function).
release-lock (function).
release-recursive-lock (function).
semaphore (type).
semaphore-p (function).
signal-semaphore (function).
start-multiprocessing (function).
thread (type).
thread-alive-p (function).
thread-name (function).
thread-yield (function).
threadp (function).
timeout (type).
wait-on-semaphore (function).
with-lock-held (macro).
with-recursive-lock-held (macro).
with-timeout (macro).
%make-thread (function).
%semaphore (structure).
%semaphore-condition-variable (reader).
(setf %semaphore-condition-variable) (writer).
%semaphore-counter (reader).
(setf %semaphore-counter) (writer).
%semaphore-lock (reader).
(setf %semaphore-lock) (writer).
%semaphore-p (function).
*no-condition-wait-timeout-message* (special variable).
binding-default-specials (function).
bordeaux-mp-condition (condition).
copy-%semaphore (function).
defbindings (macro).
defdfun (macro).
defdmacro (macro).
define-condition-wait-compiler-macro (macro).
make-%semaphore (function).
make-threading-support-error (generic function).
mark-supported (function).
message (generic reader).
signal-error-if-condition-wait-timeout (function).
signal-error-if-current-thread (function).
Definitions are sorted by export status, category, package, and then by lexicographic order.
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.
Standard bindings of printer/reader control variables as per CL:WITH-STANDARD-IO-SYNTAX.
This should be set to T if the running instance has thread support.
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.
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
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.
As for ACQUIRE-LOCK, but for recursive locks.
Returns a sequence of all of the threads. This may not be freshly-allocated, so the caller should not modify it.
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.
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.
Returns the thread object for the calling
thread. This is the same kind of object as would be returned by
MAKE-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.
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.
Wait until THREAD terminates. If THREAD has already terminated, return immediately. The return values of the thread function are returned.
Returns T if OBJECT is a lock; returns NIL otherwise.
Returns a new condition-variable object for use with CONDITION-WAIT and CONDITION-NOTIFY.
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.
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.
Create a semaphore with the supplied NAME and initial counter value COUNT.
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.
Returns T if OBJECT is a recursive lock; returns NIL otherwise.
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.
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.
Returns T if OBJECT is a semaphore; returns NIL otherwise.
Increment SEMAPHORE by COUNT. If there are threads waiting on this semaphore, then COUNT of them are woken up.
If the host implementation uses user-level threads, start the
scheduler and multiprocessing, otherwise do nothing.
It is safe to call repeatedly.
Returns true if THREAD is alive, that is, if DESTROY-THREAD has not been called on it.
Returns the name of the thread, as supplied to MAKE-THREAD.
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.
Returns true if object is a thread, otherwise NIL.
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.
The actual implementation-dependent function that creates threads.
lock.
Return a closure that binds the symbols in SPECIAL-BINDINGS and calls FUNCTION.
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.
bordeaux-mp-condition)) ¶error.
| Jump to: | %
(
A B C D F G I J L M R S T W |
|---|
| Jump to: | %
(
A B C D F G I J L M R S T W |
|---|
| Jump to: | *
C L M S |
|---|
| Jump to: | *
C L M S |
|---|
| Jump to: | %
B C D F I L M P R S T V |
|---|
| Jump to: | %
B C D F I L M P R S T V |
|---|