Next: Special Variables, 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`.