From 69e05dc39167e3103171be27887529659b709b65 Mon Sep 17 00:00:00 2001
From: Julian Graham <address@hidden(none)>
Date: Sat, 21 Jun 2008 00:55:17 -0400
Subject: [PATCH] srfi-modules.texi (SRFI-18): New sections.

---
 doc/ref/srfi-modules.texi |  345 ++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 343 insertions(+), 2 deletions(-)

diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi
index 31ba498..26b95ec 100644
--- a/doc/ref/srfi-modules.texi
+++ b/doc/ref/srfi-modules.texi
@@ -34,6 +34,7 @@ get the relevant SRFI documents from the SRFI home page
 * SRFI-14::                     Character-set library.
 * SRFI-16::                     case-lambda
 * SRFI-17::                     Generalized set!
+* SRFI-18::                     Multithreading support
 * SRFI-19::                     Time/Date library.
 * SRFI-26::                     Specializing parameters
 * SRFI-31::                     A special form `rec' for recursive evaluation
@@ -1678,6 +1679,344 @@ The same as the Guile core @code{make-procedure-with-setter}
 @end defun
 
 
address@hidden SRFI-18
address@hidden SRFI-18 - Multithreading support
address@hidden SRFI-18
+
+This is an implementation of the SRFI-18 threading and synchronization
+library.  The functions and variables described here are provided by
+
address@hidden
+(use-modules (srfi srfi-18))
address@hidden example
+
+As a general rule, the data types and functions in this SRFI-18
+implementation are compatible with the types and functions in Guile's
+core threading code.  For example, mutexes created with the SRFI-18 
address@hidden function can be passed to the built-in Guile 
+function @code{lock-mutex} (@pxref{Mutexes and Condition Variables}),
+and mutexes created with the build-in Guile function @code{make-mutex}
+can be passed to the SRFI-18 function @code{mutex-lock!}.  Cases in
+which this does not hold true are noted in the following sections.
+
address@hidden
+* SRFI-18 Threads::             Executing code 
+* SRFI-18 Mutexes::             Mutual exclusion devices
+* SRFI-18 Condition variables:: Synchronizing of groups of threads
+* SRFI-18 Time::                Representation of times and durations
+* SRFI-18 Exceptions::          Signalling and handling errors
address@hidden menu
+
address@hidden SRFI-18 Threads
address@hidden SRFI-18 Threads
+
+Threads created by SRFI-18 differ in two ways from threads created by 
+Guile's built-in thread functions.  First, a thread created by SRFI-18
address@hidden begins in a blocked state and will not start 
+execution until @code{thread-start!} is called on it.  Second, SRFI-18
+threads are constructed with a top-level exception handler that 
+captures any exceptions that are thrown on thread exit.  In all other
+regards, SRFI-18 threads are identical to normal Guile threads.
+
address@hidden current-thread
+Returns the thread that called this function.  This is the same
+procedure as the same-named built-in procedure @code{current-thread}
+(@pxref{Threads}).
address@hidden defun
+
address@hidden thread? obj
+Returns @code{#t} if @var{obj} is a thread, @code{#f} otherwise.  This
+is the same procedure as the same-named built-in procedure 
address@hidden (@pxref{Threads}).
address@hidden defun
+
address@hidden make-thread thunk [name]
+Call @code{thunk} in a new thread and with a new dynamic state,
+returning the new thread and optionally assigning it the object name
address@hidden, which may be any Scheme object.
+
+Note that the name @code{make-thread} conflicts with the 
address@hidden(ice-9 threads)} function @code{make-thread}.  Applications 
+wanting to use both of these functions will need to refer to them by 
+different names.
address@hidden defun
+
address@hidden thread-name thread
+Returns the name assigned to @var{thread} at the time of its creation,
+or @code{#f} if it was not given a name.
address@hidden defun
+
address@hidden thread-specific thread
address@hidden thread-specific-set! thread obj
+Get or set the ``object-specific'' property of @var{thread}.  In
+Guile's implementation of SRFI-18, this value is stored as an object
+property, and will be @code{#f} if not set.
address@hidden defun
+
address@hidden thread-start! thread
+Unblocks @var{thread} and allows it to begin execution if it has not
+done so already.
address@hidden defun
+
address@hidden thread-yield!
+If one or more threads are waiting to execute, calling 
address@hidden forces an immediate context switch to one of them.
+Otherwise, @code{thread-yield!} has no effect.  @code{thread-yield!} 
+behaves identically to the Guile built-in function @code{yield}.
address@hidden defun
+
address@hidden thread-sleep! timeout
+The current thread waits until the point specified by the time object
address@hidden is reached (@pxref{SRFI-18 Time}).  This blocks the 
+thread only if @var{timeout} represents a point in the future.  it is 
+an error for @var{timeout} to be @code{#f}.
address@hidden defun
+
address@hidden thread-terminate! thread
+Causes an abnormal termination of @var{thread}.  If @var{thread} is
+not already terminated, all mutexes owned by @var{thread} become
+unlocked/abandoned.  If @var{thread} is the current thread, 
address@hidden does not return.  Otherwise 
address@hidden returns an unspecified value; the termination
+of @var{thread} will occur before @code{thread-terminate!} returns.  
+Subsequent attempts to join on @var{thread} will cause a ``terminated 
+thread exception'' to be raised.
+
address@hidden is compatible with the thread cancellation
+procedures in the core threads API (@pxref{Threads}) in that if a 
+cleanup handler has been installed for the target thread, it will be 
+called before the thread exits and its return value (or exception, if
+any) will be stored for later retrieval via a call to 
address@hidden
address@hidden defun
+
address@hidden thread-join! thread [timeout [timeout-val]]
+Wait for @var{thread} to terminate and return its exit value.  When a 
+time value @var{timeout} is given, it specifies a point in time where
+the waiting should be aborted.  When the waiting is aborted, 
address@hidden is returned if it is specified; otherwise, a
address@hidden exception is raised 
+(@pxref{SRFI-18 Exceptions}).  Exceptions may also be raised if the 
+thread was terminated by a call to @code{thread-terminate!} 
+(@code{terminated-thread-exception} will be raised) or if the thread 
+exited by raising an exception that was handled by the top-level 
+exception handler (@code{uncaught-exception} will be raised; the 
+original exception can be retrieved using 
address@hidden).
address@hidden defun
+
+
address@hidden SRFI-18 Mutexes
address@hidden SRFI-18 Mutexes
+
+The behavior of Guile's built-in mutexes is parameterized via a set of
+flags passed to the @code{make-mutex} procedure in the core
+(@pxref{Mutexes and Condition Variables}).  To satisfy the requirements
+for mutexes specified by SRFI-18, the @code{make-mutex} procedure
+described below sets the following flags:
address@hidden @bullet
address@hidden
address@hidden: the mutex can be locked recursively
address@hidden
address@hidden: attempts to unlock a mutex that is already
+unlocked will not raise an exception
address@hidden
address@hidden: the mutex can be unlocked by any thread,
+not just the thread that locked it originally
address@hidden itemize
+
address@hidden make-mutex [name]
+Returns a new mutex, optionally assigning it the object name 
address@hidden, which may be any Scheme object.  The returned mutex will be
+created with the configuration described above.  Note that the name 
address@hidden conflicts with Guile core function @code{make-mutex}.
+Applications wanting to use both of these functions will need to refer 
+to them by different names.
address@hidden defun
+
address@hidden mutex-name mutex
+Returns the name assigned to @var{mutex} at the time of its creation, 
+or @code{#f} if it was not given a name.
address@hidden defun
+
address@hidden mutex-specific mutex
address@hidden mutex-specific-set! mutex obj
+Get or set the ``object-specific'' property of @var{mutex}.  In Guile's
+implementation of SRFI-18, this value is stored as an object property, 
+and will be @code{#f} if not set.
address@hidden defun
+
address@hidden mutex-state mutex
+Returns information about the state of @var{mutex}.  Possible values 
+are:
address@hidden @bullet
address@hidden
+thread @code{T}: the mutex is in the locked/owned state and thread T
+is the owner of the mutex
address@hidden 
+symbol @code{not-owned}: the mutex is in the locked/not-owned state
address@hidden
+symbol @code{abandoned}: the mutex is in the unlocked/abandoned state
address@hidden
+symbol @code{not-abandoned}: the mutex is in the 
+unlocked/not-abandoned state 
address@hidden itemize
address@hidden defun
+
address@hidden mutex-lock! mutex [timeout [thread]]
+Lock @var{mutex}, optionally specifying a time object @var{timeout}
+after which to abort the lock attempt and a thread @var{thread} giving
+a new owner for @var{mutex} different than the current thread.  This 
+procedure has the same behavior as the @code{lock-mutex} procedure in 
+the core library.
address@hidden defun
+
address@hidden mutex-unlock! mutex [condition-variable [timeout]]
+Unlock @var{mutex}, optionally specifying a condition variable
address@hidden on which to wait, either indefinitely or,
+optionally, until the time object @var{timeout} has passed, to be
+signalled.  This procedure has the same behavior as the 
address@hidden procedure in the core library.
address@hidden defun
+
+
address@hidden SRFI-18 Condition variables
address@hidden SRFI-18 Condition variables
+
+SRFI-18 does not specify a ``wait'' function for condition variables.
+Waiting on a condition variable can be simulated using the SRFI-18
address@hidden function described in the previous section, or
+Guile's built-in @code{wait-condition-variable} procedure can be used.
+
address@hidden condition-variable? obj
+Returns @code{#t} if @var{obj} is a condition variable, @code{#f}
+otherwise.  This is the same procedure as the same-named built-in 
+procedure
+(@pxref{Mutexes and Condition Variables, @code{condition-variable?}}).
address@hidden defun
+
address@hidden make-condition-variable [name]
+Returns a new condition variable, optionally assigning it the object
+name @var{name}, which may be any Scheme object.  This procedure 
+replaces a procedure of the same name in the core library.
address@hidden defun
+
address@hidden condition-variable-name condition-variable
+Returns the name assigned to @var{thread} at the time of its creation,
+or @code{#f} if it was not given a name.
address@hidden defun
+
address@hidden condition-variable-specific condition-variable
address@hidden condition-variable-specific-set! condition-variable obj
+Get or set the ``object-specific'' property of 
address@hidden  In Guile's implementation of SRFI-18, this
+value is stored as an object property, and will be @code{#f} if not 
+set.
address@hidden defun
+
address@hidden condition-variable-signal! condition-variable
address@hidden condition-variable-broadcast! condition-variable
+Wake up one thread that is waiting for @var{condition-variable}, in
+the case of @code{condition-variable-signal!}, or all threads waiting
+for it, in the case of @code{condition-variable-broadcast!}.  The
+behavior of these procedures is equivalent to that of the procedures
address@hidden and 
address@hidden in the core library.
address@hidden defun
+
+
address@hidden SRFI-18 Time
address@hidden SRFI-18 Time
+
+The SRFI-18 time functions manipulate time in two formats: a 
+``time object'' type that represents an absolute point in time in some 
+implementation-specific way; and the number of seconds since some 
+unspecified ``epoch''.  In Guile's implementation, the epoch is the
+Unix epoch, 00:00:00 UTC, January 1, 1970.
+
address@hidden current-time
+Return the current time as a time object.  This procedure replaces 
+the procedure of the same name in the core library, which returns the
+current time in seconds since the epoch.
address@hidden defun
+
address@hidden time? obj
+Returns @code{#t} if @var{obj} is a time object, @code{#f} otherwise.
address@hidden defun
+
address@hidden time->seconds time
address@hidden seconds->time seconds
+Convert between time objects and numerical values representing the
+number of seconds since the epoch.  When converting from a time object 
+to seconds, the return value is the number of seconds between 
address@hidden and the epoch.  When converting from seconds to a time 
+object, the return value is a time object that represents a time 
address@hidden seconds after the epoch.
address@hidden defun
+
+
address@hidden SRFI-18 Exceptions
address@hidden SRFI-18 Exceptions
+
+SRFI-18 exceptions are identical to the exceptions provided by 
+Guile's implementation of SRFI-34.  The behavior of exception 
+handlers invoked to handle exceptions thrown from SRFI-18 functions,
+however, differs from the conventional behavior of SRFI-34 in that
+the continuation of the handler is the same as that of the call to
+the function.  Handlers are called in a tail-recursive manner; the
+exceptions do not ``bubble up''.
+
address@hidden current-exception-handler
+Returns the current exception handler.
address@hidden defun
+
address@hidden with-exception-handler handler thunk
+Installs @var{handler} as the current exception handler and calls the
+procedure @var{thunk} with no arguments, returning its value as the 
+value of the exception.  @var{handler} must be a procedure that accepts
+a single argument. The current exception handler at the time this 
+procedure is called will be restored after the call returns.
address@hidden defun
+
address@hidden raise obj
+Raise @var{obj} as an exception.  This is the same procedure as the
+same-named procedure defined in SRFI 34.
address@hidden defun
+
address@hidden join-timeout-exception? obj
+Returns @code{#t} if @var{obj} is an exception raised as the result of 
+performing a timed join on a thread that does not exit within the
+specified timeout, @code{#f} otherwise.
address@hidden defun
+
address@hidden abandoned-mutex-exception? obj
+Returns @code{#t} if @var{obj} is an exception raised as the result of
+attempting to lock a mutex that has been abandoned by its owner thread,
address@hidden otherwise.
address@hidden defun
+
address@hidden terminated-thread-exception? obj
+Returns @code{#t} if @var{obj} is an exception raised as the result of 
+joining on a thread that exited as the result of a call to
address@hidden
address@hidden defun
+
address@hidden uncaught-exception? obj
address@hidden uncaught-exception-reason exc
address@hidden returns @code{#t} if @var{obj} is an 
+exception thrown as the result of joining a thread that exited by
+raising an exception that was handled by the top-level exception
+handler installed by @code{make-thread}.  When this occurs, the 
+original exception is preserved as part of the exception thrown by
address@hidden and can be accessed by calling 
address@hidden on that exception.  Note that
+because this exception-preservation mechanism is a side-effect of
address@hidden, joining on threads that exited as described above
+but were created by other means will not raise this 
address@hidden error.
address@hidden defun
+
+
 @node SRFI-19
 @subsection SRFI-19 - Time/Date Library
 @cindex SRFI-19
@@ -1845,8 +2184,10 @@ Return the current time of the given @var{type}.  The default
 @var{type} is @code{time-utc}.
 
 Note that the name @code{current-time} conflicts with the Guile core
address@hidden function (@pxref{Time}).  Applications wanting to
-use both will need to use a different name for one of them.
address@hidden function (@pxref{Time}) as well as the SRFI-18
address@hidden function (@pxref{SRFI-18 Time}).  Applications 
+wanting to use more than one of these functions will need to refer to
+them by different names.
 @end defun
 
 @defun time-resolution [type]
-- 
1.5.4.3