[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.22.1 Thread procedures

Builtin Class: <thread>
A thread. Each thread has an associated thunk which is evaluated by a POSIX thread. When thunk returns normally, the result is stored in the internal 'result' slot, and can be retrieved by thread-join!. When thunk terminates abnormally, either by raising an exception or terminated by thread-terminate!, the exception condition is stored in ther internal 'result exception' slot, and will be passed to the thread calling thread-join! on the terminated thread.

Each thread has its own dynamic environment and dynamic handler stack. When a thread is created, its dynamic environment is initialized by the creator's dynamic environment. The thread's dynamic handler stack is initially empty.

Access to the resouces shared by multiple threads must be protected explicitly by synchronization primitives. See section 9.22.2 Synchronization primitives.

Access to ports are serialized by Gauche. If multiple threads attempt to write to a port, their output may be interleaved but no output will be lost, and the state of the port is kept consistent. If multiple threads attempt to read from a port, a single read primitive (e.g. read, read-char or read-line) works atomically.

Signal handlers are shared by all threads, but each thread has its own signal mask. See section 6.21.6.5 Signals and threads, for details.

A thread object has the following external slots.

Instance Variable: <thread> name
A name can be associated to a thread. This is just for the convenience of the application. The primordial thread has the name "root".

Instance Variable: <thread> specific
A thread-local slot for use of the application.

Function: current-thread
[SRFI-18], [SRFI-21] Returns the current thread.

Function: thread? obj
[SRFI-18], [SRFI-21] Returns #t if obj is a thread, #f otherwise.

Function: make-thread thunk &optional name
[SRFI-18], [SRFI-21] Creates and returns a new thread. To run the thread, you need to call thread-start!.

You can provide the name of the thread by the optional argument name.

Internally, this procedure just allocates and initializes a Scheme thread object; the POSIX thread is not created until thread-start! is called.

Function: thread-name thread
[SRFI-18], [SRFI-21] Returns the value of name slot of thread.

Function: thread-specific thread
Function: thread-specific-set! thread value
[SRFI-18], [SRFI-21] Gets/sets the value of the thread's specific slot.

Function: thread-start! thread
[SRFI-18], [SRFI-21] Starts the thread. It is an error if thread is already started. Returns thread.

Function: thread-yield!
[SRFI-18], [SRFI-21] Suspends the execution of the calling thread and yields CPU to other waiting runnable threads, if any.

Function: thread-sleep! timeout
[SRFI-18], [SRFI-21] Suspends the calling thread for the period specified by timeout, which must be either a <time> object (See section 6.21.8.2 SRFI time) that specifies absolute point of time, or a real number that specifies relative point of time from the time this procedure is called in number of seconds.

After the specified time passes, thread-sleep! returns with unspecified value.

If timeout points a past time, thread-sleep! returns immediately.

Function: thread-terminate! thread
[SRFI-18], [SRFI-21] Terminates the specified thread thread. The thread is terminated and an instance of <terminated-thread-exception> is stored in the result exception field of thread.

If thread is the same as the calling thread, this procedure won't return. Otherwise, this procedure returns unspecified value.

This procedure should be used with care, since thread won't have a chance to call cleanup procedures (such as 'after' thunks of dynamic-wind) If thread is in the critical section, it leaves some state inconsistent. However, once a thread is terminated, any mutex that the thread has kept becomes 'abandoned' state, and an attempt to lock such a mutex by other thread raises an 'abandoned mutex exception', so that you will know the situation. See section 9.22.2 Synchronization primitives.

Function: thread-join! thread &optional timeout timeout-val
[SRFI-18], [SRFI-21] Waits termination of thread, or until the timeout is reached if timeout is given.

Timeout must be either a <time> object (See section 6.21.8.2 SRFI time) that specifies absolute point of time, or a real number that specifies relative point of time from the time this procedure is called in number of seconds, or #f that indicates no timeout (default).

If thread terminates normally, thread-join! returns a value which is stored in the result field of thread. If thread terminates abnormally, thread-join! raises an exception which is stored in the result exception field of thread.

If the timeout is reached, thread-join! returns timeout-val if given, or raises <join-timeout-exception>.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

This document was generated by Ken Dickey on November, 28 2002 using texi2html