Next: , Up: Threading


12.1 Threading basics

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

12.1.1 Thread Objects

— Structure: sb-thread: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: sb-thread:*current-thread*

Bound in each thread to the thread itself.

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

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: sb-thread:thread-alive-p 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: sb-thread:thread-name instance

Name of a queue. Can be assingned to using setf. Queue names can be arbitrary printable objects, and need not be unique.

12.1.2 Making, Joining, and Yielding Threads

— Function: sb-thread:make-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: sb-thread:thread-yield

Yield the processor to other threads.

— Function: sb-thread:join-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: sb-thread:interrupt-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: sb-thread:terminate-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: sb-thread:symbol-value-in-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: sb-thread:thread-error

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: sb-thread:thread-error-thread condition

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

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

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: sb-thread:join-thread-error

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.