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

9.22.2 Synchronization primitives

Builtin Class: <mutex>
A primitive synchronization device. It can take one of four states: locked/owned, locked/not-owned, unlocked/abandoned and unlocked/not-abandoned. A mutex can be locked (by mutex-lock!) only if it is in unlocked state. An 'owned' mutex keeps a thread that owns it. Typically an owner thread is the one that locked the mutex, but you can make a thread other than the locking thread own a mutex. A mutex becomes unlocked either by mutex-unlock! or the owner thread terminates. In the former case, a mutex becomes unlocked/not-abandoned state. In the latter case, a mutex becomes unlocked/abandoned state.

A mutex has the following external slots.

Instance Variable: <mutex> name
The name of the mutex.

Instance Variable: <mutex> state
The state of the mutex. This is a read-only slot. See the descrption of mutex-state below.

Instance Variable: <mutex> specific
A slot an application can keep arbitrary data. For example, an application can implement a 'recursive' mutex using the specific field.

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

Function: make-mutex &optional name
[SRFI-18], [SRFI-21] Creates and returns a new mutex object. When created, the mutex is in unlocked/not-abandoned state. Optionally, you can give a name to the mutex.

Function: mutex-name mutex
[SRFI-18], [SRFI-21] Returns the name of the mutex.

Function: mutex-specific mutex
Function: mutex-specific-set! mutex value
[SRFI-18], [SRFI-21] Gets/sets the specific value of the mutex.

Function: mutex-state mutex
[SRFI-18], [SRFI-21] Returns the state of mutex, which may be one of the followings:

a thread
The mutex is locked/owned, and the owner is the returned thread.
symbol not-owned
The mutex is locked/not-owned.
symbol abandoned
The mutex is unlocked/abandoned.
symbol not-abandoned
The mutex is unlocked/not-abandoned.

Function: mutex-lock! mutex &optional timeout thread
[SRFI-18], [SRFI-21] Locks mutex. If mutex is in unlocked/not-abandoned state, this procedure changes its state to locked state exclusively. By default, mutex becomes locked/owned state, owned by the calling thread. You can give other owner thread as thread argument. If thread argument is given and #f, the mutex becomes locked/not-owned state.

If mutex is in unlocked/abandoned state, that is, some other thread has been terminated without unlocking it, this procedure signals 'abandoned mutex exception' (See section 9.22.3 Thread exceptions) after changing the state of mutex.

If mutex is in locked state and timeout is omitted or #f, this procedure blocks until mutex becomes unlocked. If timeout is specified, mutex-lock! returns when the specified time reaches in case it couldn't obtain a lock. You can give timeout an absolute point of time (by <time> object, See section SRFI time), or a relative time (by a real number).

Mutex-lock! returns #t if mutex is successfully locked, or #f if timeout reached.

Note that mutex itself doesn't implements a 'recursive lock' feature; that is, if a thread that has locked mutex tries to lock mutex again, the thread blocks. It is not difficult, however, to implement a recursive lock semantics on top of this mutex. The following example is taken from SRFI-18 document:

(define (mutex-lock-recursively! mutex)
  (if (eq? (mutex-state mutex) (current-thread))
      (let ((n (mutex-specific mutex)))
        (mutex-specific-set! mutex (+ n 1)))
        (mutex-lock! mutex)
        (mutex-specific-set! mutex 0))))

(define (mutex-unlock-recursively! mutex)
  (let ((n (mutex-specific mutex)))
    (if (= n 0)
        (mutex-unlock! mutex)
        (mutex-specific-set! mutex (- n 1)))))

Function: mutex-unlock! mutex &optional condition-variable timeout
[SRFI-18], [SRFI-21] Unlocks mutex. The state of mutex becomes unlocked/not-abandoned. It is allowed to unlock a mutex that is not owned by the calling thread.

If optional condition-variable is given, mutex-unlock! serves the "condition variable wait" operation (e.g. pthread_cond_wait in POSIX threads). The current thread atomically wait on condition-variable and unlocks mutex. The thread will be unblocked when other thread signals on condition-variable (see condition-variable-signal! and condition-variable-broadcast! below), or timeout reaches if it is supplied. The timeout argument can be either a <time> object to represent an absolute time point (See section SRFI time), a real number to represent a relative time in seconds, or #f which means never. The calling thread may be unblocked prematurely, so it should reacquire the lock of mutex and checks the condition, as in the follwing example (it is taken from SRFI-18 document):

(let loop ()
  (mutex-lock! m)
  (if (condition-is-true?)
        (mutex-unlock! m))
        (mutex-unlock! m cv)

Builtin Class: <condition-variable>
A condition variable keeps a set of threads that are waiting for a certain condition to be true. When a thread modifies the state of the concerned condition, it can call condition-variable-signal! or condition-variable-broadcast!, which unblock one or more waiting threads so that they can check if the condition is satisfied.

A condition variable object has the following slots.

Instance Variable: <mutex> name
The name of the condition variable.

Instance Variable: <mutex> specific
A slot an application can keep arbitrary data.

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

Function: make-condition-variable &optional name
[SRFI-18], [SRFI-21] Returns a new condition variable. You can give its name by optional name argument.

Function: condition-variable-name cv
[SRFI-18], [SRFI-21] Returns the name of the condition variable.

Function: condition-variable-specific cv
Function: condition-variable-specific-set! cv value
[SRFI-18], [SRFI-21] Gets/sets the specific value of the condition variable.

Function: condition-variable-signal! cv
[SRFI-18], [SRFI-21] If there are threads waiting on cv, causes the scheduler to select one of them and to make it runnable.

Function: condition-variable-broadcast! cv
[SRFI-18], [SRFI-21] Unblocks all the threads waiting on cv.

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

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