6.22.1 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).

To use these facilities, load the (ice-9 threads) module.

(use-modules (ice-9 threads))

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. Only threads that were created with call-with-new-thread or scm_spawn_thread can be joinable; attempting to join a foreign thread will raise an error.

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

C Function: scm_yield (thread)

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 . values

C Function: scm_cancel_thread (thread)

Asynchronously interrupt thread and ask it to terminate. dynamic-wind post thunks will run, but throw handlers will not. If thread has already terminated or been signaled to terminate, this function is a no-op. Calling join-thread on the thread will return the given values, if the cancel succeeded.

Under the hood, thread cancellation uses system-async-mark and abort-to-prompt. See Asyncs for more on asynchronous interrupts.

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.

One often wants to limit the number of threads running to be proportional to the number of available processors. These interfaces are therefore exported by (ice-9 threads) as well.

Scheme Procedure: total-processor-count

C Function: scm_total_processor_count ()

Return the total number of processors of the machine, which is guaranteed to be at least 1. A “processor” here is a thread execution unit, which can be either:

• an execution core in a (possibly multi-core) chip, in a (possibly multi- chip) module, in a single computer, or
• a thread execution unit inside a core in the case of hyper-threaded CPUs.

Which of the two definitions is used, is unspecified.

Scheme Procedure: current-processor-count

C Function: scm_current_processor_count ()

Like total-processor-count, but return the number of processors available to the current process. See setaffinity and getaffinity for more information.