Threads, Mutexes, Asyncs and Dynamic Roots

[FIXME: This is pasted in from Tom Lord's original guile.texi chapter plus the Cygnus programmer's manual; it should be *very* carefully reviewed and largely reorganized.]

Arbiters

Arbiters are synchronization objects. They are created with make-arbiter. Two or more threads can synchronize on an arbiter by trying to lock it using try-arbiter. This call will succeed if no other thread has called try-arbiter on the arbiter yet, otherwise it will fail and return #f. Once an arbiter is successfully locked, it cannot be locked by another thread until the thread holding the arbiter calls release-arbiter to unlock it.

Scheme Procedure: make-arbiter name

C Function: scm_make_arbiter (name)

Return an object of type arbiter and name name. Its state is initially unlocked. Arbiters are a way to achieve process synchronization.

Scheme Procedure: try-arbiter arb

C Function: scm_try_arbiter (arb)

Return #t and lock the arbiter arb if the arbiter was unlocked. Otherwise, return #f.

Scheme Procedure: release-arbiter arb

C Function: scm_release_arbiter (arb)

Return #t and unlock the arbiter arb if the arbiter was locked. Otherwise, return #f.

Asyncs

An async is a pair of one thunk (a parameterless procedure) and a mark. Setting the mark on an async guarantees that the thunk will be executed somewhen in the future (asynchronously). Setting the mark more than once is satisfied by one execution of the thunk.

Guile supports two types of asyncs: Normal asyncs and system asyncs. They differ in that marked system asyncs are executed implicitly as soon as possible, whereas normal asyncs have to be invoked explicitly. System asyncs are held in an internal data structure and are maintained by Guile.

Normal asyncs are created with async, system asyncs with system-async. They are marked with async-mark or system-async-mark, respectively.

Scheme Procedure: async thunk

C Function: scm_async (thunk)

Create a new async for the procedure thunk.

Scheme Procedure: system-async thunk

C Function: scm_system_async (thunk)

Create a new async for the procedure thunk. Also add it to the system's list of active async objects.

Scheme Procedure: async-mark a

C Function: scm_async_mark (a)

Mark the async a for future execution.

Scheme Procedure: system-async-mark a

C Function: scm_system_async_mark (a)

Mark the async a for future execution.

As already mentioned above, system asyncs are executed automatically. Normal asyncs have to be explicitly invoked by storing one or more of them into a list and passing them to run-asyncs.

Scheme Procedure: run-asyncs list_of_a

C Function: scm_run_asyncs (list_of_a)

Execute all thunks from the asyncs of the list list_of_a.

Automatic invocation of system asyncs can be temporarily disabled by calling mask-signals and unmask-signals. Setting the mark while async execution is disabled will nevertheless cause the async to run once execution is enabled again. Please note that calls to these procedures should always be paired, and they must not be nested, e.g. no mask-signals is allowed if another one is still active.

Scheme Procedure: mask-signals

C Function: scm_mask_signals ()

Mask signals. The returned value is not specified.

Scheme Procedure: unmask-signals

C Function: scm_unmask_signals ()

Unmask signals. The returned value is not specified.

Scheme Procedure: noop . args

C Function: scm_noop (args)

Do nothing. When called without arguments, return #f, otherwise return the first argument.

Dynamic Roots

A dynamic root is a root frame of Scheme evaluation. The top-level repl, for example, is an instance of a dynamic root.

Each dynamic root has its own chain of dynamic-wind information. Each has its own set of continuations, jump-buffers, and pending CATCH statements which are inaccessible from the dynamic scope of any other dynamic root.

In a thread-based system, each thread has its own dynamic root. Therefore, continuations created by one thread may not be invoked by another.

Even in a single-threaded system, it is sometimes useful to create a new dynamic root. For example, if you want to apply a procedure, but to not allow that procedure to capture the current continuation, calling the procedure under a new dynamic root will do the job.

Scheme Procedure: call-with-dynamic-root thunk handler

C Function: scm_call_with_dynamic_root (thunk, handler)

Evaluate (thunk) in a new dynamic context, returning its value.

If an error occurs during evaluation, apply handler to the arguments to the throw, just as throw would. If this happens, handler is called outside the scope of the new root -- it is called in the same dynamic context in which call-with-dynamic-root was evaluated.

If thunk captures a continuation, the continuation is rooted at the call to thunk. In particular, the call to call-with-dynamic-root is not captured. Therefore, call-with-dynamic-root always returns at most one time.

Before calling thunk, the dynamic-wind chain is un-wound back to the root and a new chain started for thunk. Therefore, this call may not do what you expect:

;; Almost certainly a bug:
(with-output-to-port
 some-port

 (lambda ()
   (call-with-dynamic-root
    (lambda ()
      (display 'fnord)
      (newline))
    (lambda (errcode) errcode))))

The problem is, on what port will `fnord' be displayed? You might expect that because of the with-output-to-port that it will be displayed on the port bound to some-port. But it probably won't -- before evaluating the thunk, dynamic winds are unwound, including those created by with-output-to-port. So, the standard output port will have been re-set to its default value before display is evaluated.

(This function was added to Guile mostly to help calls to functions in C libraries that can not tolerate non-local exits or calls that return multiple times. If such functions call back to the interpreter, it should be under a new dynamic root.)

Scheme Procedure: dynamic-root

C Function: scm_dynamic_root ()

Return an object representing the current dynamic root.

These objects are only useful for comparison using eq?. They are currently represented as numbers, but your code should in no way depend on this.

Scheme Procedure: quit [exit_val]

Throw back to the error handler of the current dynamic root.

If integer exit_val is specified and if Guile is being used stand-alone and if quit is called from the initial dynamic-root, exit_val becomes the exit status of the Guile process and the process exits.

When Guile is run interactively, errors are caught from within the read-eval-print loop. An error message will be printed and abort called. A default set of signal handlers is installed, e.g., to allow user interrupt of the interpreter.

It is possible to switch to a "batch mode", in which the interpreter will terminate after an error and in which all signals cause their default actions. Switching to batch mode causes any handlers installed from Scheme code to be removed. An example of where this is useful is after forking a new process intended to run non-interactively.

Scheme Procedure: batch-mode?

Returns a boolean indicating whether the interpreter is in batch mode.

Scheme Procedure: set-batch-mode?! arg

If arg is true, switches the interpreter to batch mode. The #f case has not been implemented.

Threads

[NOTE: this chapter was written for Cygnus Guile and has not yet been updated for the Guile 1.x release.]

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

Scheme Procedure: call-with-new-thread thunk error-handler

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-handler, 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-handler 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 caller's thread.

All the evaluation rules for dynamic roots apply to threads.

Scheme Procedure: join-thread thread

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

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: make-mutex

Create a new mutex object.

Scheme Procedure: 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.

Scheme Procedure: 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.

Scheme Procedure: make-condition-variable

Scheme Procedure: wait-condition-variable cond-var mutex

Scheme Procedure: signal-condition-variable cond-var

Higher level thread procedures

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

Scheme Procedure: %thread-handler tag args...

This procedure is specified as the standard error-handler for make-thread and begin-thread. If the number of args is three or more, use display-error, otherwise display a message "uncaught throw to tag". All output is sent to the port specified by current-error-port.

Before display, global var the-last-stack is set to #f and signals are unmasked with unmask-signals.

[FIXME: Why distinguish based on number of args?! Cue voodoo music here.]

macro: make-thread proc [args...]

Apply proc to args in a new thread formed by call-with-new-thread using %thread-handler as the error handler.

macro: begin-thread first [rest...]

Evaluate forms first and rest in a new thread formed by call-with-new-thread using %thread-handler as the error handler.

macro: with-mutex m [body...]

Lock mutex m, evaluate body, and then unlock m. These sub-operations form the branches of a dynamic-wind.

macro: monitor first [rest...]

Evaluate forms first and rest under a newly created anonymous mutex, using with-mutex.

[FIXME: Is there any way to access the mutex?]

Fluids

Fluids are objects to store values in. They have a few properties which make them useful in certain situations: Fluids can have one value per dynamic root (see section Dynamic Roots), so that changes to the value in a fluid are only visible in the same dynamic root. Since threads are executed in separate dynamic roots, fluids can be used for thread local storage (see section Threads).

Fluids can be used to simulate dynamically scoped variables. These are used in several (especially in older) dialects of lisp, such as in Emacs Lisp, and they work a bit like global variables in that they can be modified by the caller of a procedure, and the called procedure will see the changes. With lexically scoped variables--which are normally used in Scheme--this cannot happen. See the description of with-fluids* below for details.

New fluids are created with make-fluid and fluid? is used for testing whether an object is actually a fluid.

Scheme Procedure: make-fluid

C Function: scm_make_fluid ()

Return a newly created fluid. Fluids are objects of a certain type (a smob) that can hold one SCM value per dynamic root. That is, modifications to this value are only visible to code that executes within the same dynamic root as the modifying code. When a new dynamic root is constructed, it inherits the values from its parent. Because each thread executes in its own dynamic root, you can use fluids for thread local storage.

Scheme Procedure: fluid? obj

C Function: scm_fluid_p (obj)

Return #t iff obj is a fluid; otherwise, return #f.

The values stored in a fluid can be accessed with fluid-ref and fluid-set!.

Scheme Procedure: fluid-ref fluid

C Function: scm_fluid_ref (fluid)

Return the value associated with fluid in the current dynamic root. If fluid has not been set, then return #f.

Scheme Procedure: fluid-set! fluid value

C Function: scm_fluid_set_x (fluid, value)

Set the value associated with fluid in the current dynamic root.

with-fluids* temporarily changes the values of one or more fluids, so that the given procedure and each procedure called by it access the given values. After the procedure returns, the old values are restored.

Scheme Procedure: with-fluids* fluids values thunk

C Function: scm_with_fluids (fluids, values, thunk)

Set fluids to values temporary, and call thunk. fluids must be a list of fluids and values must be the same number of their values to be applied. Each substitution is done one after another. thunk must be a procedure with no argument.

Go to the first, previous, next, last section, table of contents.