Next: , Up: Threading


12.1 Threading basics

     (make-thread (lambda () (write-line "Hello, world")))

12.1.1 Thread Objects

— Structure: thread [sb-thread]

Class precedence list: thread, structure-object, t

Thread type. Do not rely on threads being structs as it may change in future versions.

— Variable: *current-thread* [sb-thread]

Bound in each thread to the thread itself.

— Function: list-all-threads [sb-thread]

Return a list of the live threads. Note that the return value is potentially stale even before the function returns, as new threads may be created and old ones may exit at any time.

— Function: thread-alive-p [sb-thread] thread

Return t if thread is still alive. Note that the return value is potentially stale even before the function returns, as the thread may exit at any time.

— Function: thread-name [sb-thread] instance

Name of a mailbox. SETFable.

12.1.2 Making, Joining, and Yielding Threads

— Function: make-thread [sb-thread] function &key name

Create a new thread of name that runs function. When the function returns the thread exits. The return values of function are kept around and can be retrieved by join-thread.

— Function: thread-yield [sb-thread]

Yield the processor to other threads.

— Function: join-thread [sb-thread] thread &key default

Suspend current thread until thread exits. Returns the result values of the thread function. If the thread does not exit normally, return default if given or else signal join-thread-error.

12.1.3 Asynchronous Operations

— Function: interrupt-thread [sb-thread] thread function

Interrupt the live thread and make it run function. A moderate degree of care is expected for use of interrupt-thread, due to its nature: if you interrupt a thread that was holding important locks then do something that turns out to need those locks, you probably won't like the effect. function runs with interrupts disabled, but with-interrupts is allowed in it. Keep in mind that many things may enable interrupts (GET-MUTEX when contended, for instance) so the first thing to do is usually a with-interrupts or a without-interrupts. Within a thread interrupts are queued, they are run in same the order they were sent.

— Function: terminate-thread [sb-thread] thread

Terminate the thread identified by thread, by causing it to run sb-ext:quit - the usual cleanup forms will be evaluated

12.1.4 Miscellaneous Operations

— Function: symbol-value-in-thread [sb-thread] symbol thread &optional errorp

Return the local value of symbol in thread, and a secondary value of t on success.

If the value cannot be retrieved (because the thread has exited or because it has no local binding for NAME) and errorp is true signals an error of type symbol-value-in-thread-error; if errorp is false returns a primary value of nil, and a secondary value of nil.

Can also be used with setf to change the thread-local value of symbol.

symbol-value-in-thread is primarily intended as a debugging tool, and not as a mechanism for inter-thread communication.

12.1.5 Error Conditions

— Condition: thread-error [sb-thread]

Class precedence list: thread-error, error, serious-condition, condition, t

Conditions of type thread-error are signalled when thread operations fail. The offending thread is initialized by the :thread initialization argument and read by the function thread-error-thread.

— Function: thread-error-thread [sb-thread] condition

Return the offending thread that the thread-error pertains to.

— Condition: interrupt-thread-error [sb-thread]

Class precedence list: interrupt-thread-error, thread-error, error, serious-condition, condition, t

Signalled when interrupting a thread fails because the thread has already exited. The offending thread can be accessed using thread-error-thread.

— Condition: join-thread-error [sb-thread]

Class precedence list: join-thread-error, thread-error, error, serious-condition, condition, t

Signalled when joining a thread fails due to abnormal exit of the thread to be joined. The offending thread can be accessed using thread-error-thread.