Guile threads reference

Here is a the reference for Guile's threads. In this chapter I simply quote verbatim Tom Lord's description of the low-level primitives written in C (basically an interface to the POSIX threads library) and Anthony Green's description of the higher-level thread procedures written in scheme.

When using Guile threads, keep in mind that each guile thread is executed in a new dynamic root.

• Low level thread primitives
• Higher level thread procedures

Low level thread primitives

Function: with-new-thread thunk error-thunk

Evaluate (thunk) in a new thread, and new dynamic context, returning a new thread object representing the thread.

If an error occurs during evaluation, call error-thunk, passing it an error code describing the condition. [Error codes are currently meaningless integers. In the future, real values will be specified.] If this happens, the error-thunk is called outside the scope of the new root -- it is called in the same dynamic context in which with-new-thread was evaluated, but not in the callers thread.

All the evaluation rules for dynamic roots apply to threads.

Function: join-thread thread

Suspend execution of the calling thread until the target thread terminates, unless the target thread has already terminated.

Function: 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.

Function: make-mutex

Create a new mutex object.

Function: lock-mutex mutex

Lock mutex. If the mutex is already locked, the calling thread blocks until the mutex becomes available. The function returns when the calling thread owns the lock on mutex.

Function: unlock-mutex mutex

Unlocks mutex if the calling thread owns the lock on mutex. Calling unlock-mutex on a mutex not owned by the current thread results in undefined behaviour. Once a mutex has been unlocked, one thread blocked on mutex is awakened and grabs the mutex lock.

Higher level thread procedures

Function: with-new-thread thunk error-thunk

Evaluate (thunk) in a new thread, and new dynamic context, returning a new thread object representing the thread.

If an error occurs during evaluation, call error-thunk, passing it an error code describing the condition. [Error codes are currently meaningless integers. In the future, real values will be specified.] If this happens, the error-thunk is called outside the scope of the new root -- it is called in the same dynamic context in which with-new-thread was evaluated, but not in the callers thread.

All the evaluation rules for dynamic roots apply to threads.

Function: join-thread thread

Suspend execution of the calling thread until the target thread terminates, unless the target thread has already terminated.

Function: 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.

Function: make-mutex

Create a new mutex object.

Function: lock-mutex mutex

Lock mutex. If the mutex is already locked, the calling thread blocks until the mutex becomes available. The function returns when the calling thread owns the lock on mutex.

Function: unlock-mutex mutex

Unlocks mutex if the calling thread owns the lock on mutex. Calling unlock-mutex on a mutex not owned by the current thread results in undefined behaviour. Once a mutex has been unlocked, one thread blocked on mutex is awakened and grabs the mutex lock.