Warning: This is the manual of the legacy Guile 2.0 series. You may want to read the manual of the current stable series instead.

6.21.3 Threads

Guile supports POSIX threads, unless it was configured with --without-threads or the host lacks POSIX thread support. When thread support is available, the threads feature is provided (see provided?).

The procedures below manipulate Guile threads, which are wrappers around the system’s POSIX threads. For application-level parallelism, using higher-level constructs, such as futures, is recommended (see Futures).

Scheme Procedure: all-threads

C Function: scm_all_threads ()

Return a list of all threads.

Scheme Procedure: current-thread

C Function: scm_current_thread ()

Return the thread that called this function.

Scheme Procedure: call-with-new-thread thunk [handler]

Call thunk in a new thread and with a new dynamic state, returning the new thread. The procedure thunk is called via with-continuation-barrier.

When handler is specified, then thunk is called from within a catch with tag #t that has handler as its handler. This catch is established inside the continuation barrier.

Once thunk or handler returns, the return value is made the exit value of the thread and the thread is terminated.

C Function: SCM scm_spawn_thread (scm_t_catch_body body, void *body_data, scm_t_catch_handler handler, void *handler_data)

Call body in a new thread, passing it body_data, returning the new thread. The function body is called via scm_c_with_continuation_barrier.

When handler is non-NULL, body is called via scm_internal_catch with tag SCM_BOOL_T that has handler and handler_data as the handler and its data. This catch is established inside the continuation barrier.

Once body or handler returns, the return value is made the exit value of the thread and the thread is terminated.

Scheme Procedure: thread? obj

C Function: scm_thread_p (obj)

Return #t ff obj is a thread; otherwise, return #f.

Scheme Procedure: join-thread thread [timeout [timeoutval]]

C Function: scm_join_thread (thread)

C Function: scm_join_thread_timed (thread, timeout, timeoutval)

Wait for thread to terminate and return its exit value. Threads that have not been created with call-with-new-thread or scm_spawn_thread have an exit value of #f. When timeout is given, it specifies a point in time where the waiting should be aborted. It can be either an integer as returned by current-time or a pair as returned by gettimeofday. When the waiting is aborted, timeoutval is returned (if it is specified; #f is returned otherwise).

Scheme Procedure: thread-exited? thread

C Function: scm_thread_exited_p (thread)

Return #t if thread has exited, or #f otherwise.

Scheme Procedure: yield

If one or more threads are waiting to execute, calling yield forces an immediate context switch to one of them. Otherwise, yield has no effect.

Scheme Procedure: cancel-thread thread

C Function: scm_cancel_thread (thread)

Asynchronously notify thread to exit. Immediately after receiving this notification, thread will call its cleanup handler (if one has been set) and then terminate, aborting any evaluation that is in progress.

Because Guile threads are isomorphic with POSIX threads, thread will not receive its cancellation signal until it reaches a cancellation point. See your operating system’s POSIX threading documentation for more information on cancellation points; note that in Guile, unlike native POSIX threads, a thread can receive a cancellation notification while attempting to lock a mutex.

Scheme Procedure: set-thread-cleanup! thread proc

C Function: scm_set_thread_cleanup_x (thread, proc)

Set proc as the cleanup handler for the thread thread. proc, which must be a thunk, will be called when thread exits, either normally or by being canceled. Thread cleanup handlers can be used to perform useful tasks like releasing resources, such as locked mutexes, when thread exit cannot be predicted.

The return value of proc will be set as the exit value of thread.

To remove a cleanup handler, pass #f for proc.

Scheme Procedure: thread-cleanup thread

C Function: scm_thread_cleanup (thread)

Return the cleanup handler currently installed for the thread thread. If no cleanup handler is currently installed, thread-cleanup returns #f.

Higher level thread procedures are available by loading the (ice-9 threads) module. These provide standardized thread creation.

macro: make-thread proc arg …

Apply proc to arg … in a new thread formed by call-with-new-thread using a default error handler that display the error to the current error port. The arg … expressions are evaluated in the new thread.

macro: begin-thread expr1 expr2 …

Evaluate forms expr1 expr2 … in a new thread formed by call-with-new-thread using a default error handler that display the error to the current error port.