7.5.15.1 SRFI-18 Threads

Threads created by SRFI-18 differ in two ways from threads created by Guile’s built-in thread functions. First, a thread created by SRFI-18 make-thread begins in a blocked state and will not start execution until thread-start! is called on it. Second, SRFI-18 threads are constructed with a top-level exception handler that captures any exceptions that are thrown on thread exit.

SRFI-18 threads are disjoint from Guile’s primitive threads. See Threads, for more on Guile’s primitive facility.

Function: current-thread

Returns the thread that called this function. This is the same procedure as the same-named built-in procedure current-thread (see Threads).

Function: thread? obj

Returns #t if obj is a thread, #f otherwise. This is the same procedure as the same-named built-in procedure thread? (see Threads).

Function: make-thread thunk [name]

Call thunk in a new thread and with a new dynamic state, returning the new thread and optionally assigning it the object name name, which may be any Scheme object.

Note that the name make-thread conflicts with the (ice-9 threads) function make-thread. Applications wanting to use both of these functions will need to refer to them by different names.

Function: thread-name thread

Returns the name assigned to thread at the time of its creation, or #f if it was not given a name.

Function: thread-specific thread

Function: thread-specific-set! thread obj

Get or set the “object-specific” property of thread. In Guile’s implementation of SRFI-18, this value is stored as an object property, and will be #f if not set.

Function: thread-start! thread

Unblocks thread and allows it to begin execution if it has not done so already.

Function: thread-yield!

If one or more threads are waiting to execute, calling thread-yield! forces an immediate context switch to one of them. Otherwise, thread-yield! has no effect. thread-yield! behaves identically to the Guile built-in function yield.

Function: thread-sleep! timeout

The current thread waits until the point specified by the time object timeout is reached (see SRFI-18 Time). This blocks the thread only if timeout represents a point in the future. it is an error for timeout to be #f.

Function: thread-terminate! thread

Causes an abnormal termination of thread. If thread is not already terminated, all mutexes owned by thread become unlocked/abandoned. If thread is the current thread, thread-terminate! does not return. Otherwise thread-terminate! returns an unspecified value; the termination of thread will occur before thread-terminate! returns. Subsequent attempts to join on thread will cause a “terminated thread exception” to be raised.

thread-terminate! is compatible with the thread cancellation procedures in the core threads API (see Threads) in that if a cleanup handler has been installed for the target thread, it will be called before the thread exits and its return value (or exception, if any) will be stored for later retrieval via a call to thread-join!.

Function: thread-join! thread [timeout [timeout-val]]

Wait for thread to terminate and return its exit value. When a time value timeout is given, it specifies a point in time where the waiting should be aborted. When the waiting is aborted, timeout-val is returned if it is specified; otherwise, a join-timeout-exception exception is raised (see SRFI-18 Exceptions). Exceptions may also be raised if the thread was terminated by a call to thread-terminate! (terminated-thread-exception will be raised) or if the thread exited by raising an exception that was handled by the top-level exception handler (uncaught-exception will be raised; the original exception can be retrieved using uncaught-exception-reason).