Yikes, didn't mean for it to take this long. Work got crazy, then my
laptop died. At any rate, find attached a draft of an SRFI-18
section. Let me know what you think. Apologies in advance for any
punctuation screw-ups or missing spaces.
On Mon, Jun 2, 2008 at 12:48 AM, Julian Graham <[EMAIL PROTECTED]> wrote:
>> BTW, it'd be nice to have an "SRFI-18" node in the manual. :-)
>
> Working on it... Should have something for you in a few days.
From 69e05dc39167e3103171be27887529659b709b65 Mon Sep 17 00:00:00 2001
From: Julian Graham <[EMAIL PROTECTED](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
[EMAIL PROTECTED] SRFI-18
[EMAIL PROTECTED] SRFI-18 - Multithreading support
[EMAIL PROTECTED] SRFI-18
+
+This is an implementation of the SRFI-18 threading and synchronization
+library. The functions and variables described here are provided by
+
[EMAIL PROTECTED]
+(use-modules (srfi srfi-18))
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] 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.
+
[EMAIL PROTECTED]
+* 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
[EMAIL PROTECTED] menu
+
[EMAIL PROTECTED] SRFI-18 Threads
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] 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.
+
[EMAIL PROTECTED] 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}).
[EMAIL PROTECTED] defun
+
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] (@pxref{Threads}).
[EMAIL PROTECTED] defun
+
[EMAIL PROTECTED] 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
[EMAIL PROTECTED], which may be any Scheme object.
+
+Note that the name @code{make-thread} conflicts with the
[EMAIL PROTECTED](ice-9 threads)} function @code{make-thread}. Applications
+wanting to use both of these functions will need to refer to them by
+different names.
[EMAIL PROTECTED] defun
+
[EMAIL PROTECTED] 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.
[EMAIL PROTECTED] defun
+
[EMAIL PROTECTED] thread-specific thread
[EMAIL PROTECTED] 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.
[EMAIL PROTECTED] defun
+
[EMAIL PROTECTED] thread-start! thread
+Unblocks @var{thread} and allows it to begin execution if it has not
+done so already.
[EMAIL PROTECTED] defun
+
[EMAIL PROTECTED] thread-yield!
+If one or more threads are waiting to execute, calling
[EMAIL PROTECTED] 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}.
[EMAIL PROTECTED] defun
+
[EMAIL PROTECTED] thread-sleep! timeout
+The current thread waits until the point specified by the time object
[EMAIL PROTECTED] 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}.
[EMAIL PROTECTED] defun
+
[EMAIL PROTECTED] 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,
[EMAIL PROTECTED] does not return. Otherwise
[EMAIL PROTECTED] 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.
+
[EMAIL PROTECTED] 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
[EMAIL PROTECTED]
[EMAIL PROTECTED] defun
+
[EMAIL PROTECTED] 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,
[EMAIL PROTECTED] is returned if it is specified; otherwise, a
[EMAIL PROTECTED] 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
[EMAIL PROTECTED]).
[EMAIL PROTECTED] defun
+
+
[EMAIL PROTECTED] SRFI-18 Mutexes
[EMAIL PROTECTED] 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:
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED]
[EMAIL PROTECTED]: the mutex can be locked recursively
[EMAIL PROTECTED]
[EMAIL PROTECTED]: attempts to unlock a mutex that is already
+unlocked will not raise an exception
[EMAIL PROTECTED]
[EMAIL PROTECTED]: the mutex can be unlocked by any thread,
+not just the thread that locked it originally
[EMAIL PROTECTED] itemize
+
[EMAIL PROTECTED] make-mutex [name]
+Returns a new mutex, optionally assigning it the object name
[EMAIL PROTECTED], which may be any Scheme object. The returned mutex will be
+created with the configuration described above. Note that the name
[EMAIL PROTECTED] 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.
[EMAIL PROTECTED] defun
+
[EMAIL PROTECTED] 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.
[EMAIL PROTECTED] defun
+
[EMAIL PROTECTED] mutex-specific mutex
[EMAIL PROTECTED] 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.
[EMAIL PROTECTED] defun
+
[EMAIL PROTECTED] mutex-state mutex
+Returns information about the state of @var{mutex}. Possible values
+are:
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED]
+thread @code{T}: the mutex is in the locked/owned state and thread T
+is the owner of the mutex
[EMAIL PROTECTED]
+symbol @code{not-owned}: the mutex is in the locked/not-owned state
[EMAIL PROTECTED]
+symbol @code{abandoned}: the mutex is in the unlocked/abandoned state
[EMAIL PROTECTED]
+symbol @code{not-abandoned}: the mutex is in the
+unlocked/not-abandoned state
[EMAIL PROTECTED] itemize
[EMAIL PROTECTED] defun
+
[EMAIL PROTECTED] 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.
[EMAIL PROTECTED] defun
+
[EMAIL PROTECTED] mutex-unlock! mutex [condition-variable [timeout]]
+Unlock @var{mutex}, optionally specifying a condition variable
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] procedure in the core library.
[EMAIL PROTECTED] defun
+
+
[EMAIL PROTECTED] SRFI-18 Condition variables
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] function described in the previous section, or
+Guile's built-in @code{wait-condition-variable} procedure can be used.
+
[EMAIL PROTECTED] 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?}}).
[EMAIL PROTECTED] defun
+
[EMAIL PROTECTED] 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.
[EMAIL PROTECTED] defun
+
[EMAIL PROTECTED] 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.
[EMAIL PROTECTED] defun
+
[EMAIL PROTECTED] condition-variable-specific condition-variable
[EMAIL PROTECTED] condition-variable-specific-set! condition-variable obj
+Get or set the ``object-specific'' property of
[EMAIL PROTECTED] In Guile's implementation of SRFI-18, this
+value is stored as an object property, and will be @code{#f} if not
+set.
[EMAIL PROTECTED] defun
+
[EMAIL PROTECTED] condition-variable-signal! condition-variable
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] and
[EMAIL PROTECTED] in the core library.
[EMAIL PROTECTED] defun
+
+
[EMAIL PROTECTED] SRFI-18 Time
[EMAIL PROTECTED] 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.
+
[EMAIL PROTECTED] 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.
[EMAIL PROTECTED] defun
+
[EMAIL PROTECTED] time? obj
+Returns @code{#t} if @var{obj} is a time object, @code{#f} otherwise.
[EMAIL PROTECTED] defun
+
[EMAIL PROTECTED] time->seconds time
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] and the epoch. When converting from seconds to a time
+object, the return value is a time object that represents a time
[EMAIL PROTECTED] seconds after the epoch.
[EMAIL PROTECTED] defun
+
+
[EMAIL PROTECTED] SRFI-18 Exceptions
[EMAIL PROTECTED] 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''.
+
[EMAIL PROTECTED] current-exception-handler
+Returns the current exception handler.
[EMAIL PROTECTED] defun
+
[EMAIL PROTECTED] 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.
[EMAIL PROTECTED] defun
+
[EMAIL PROTECTED] raise obj
+Raise @var{obj} as an exception. This is the same procedure as the
+same-named procedure defined in SRFI 34.
[EMAIL PROTECTED] defun
+
[EMAIL PROTECTED] 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.
[EMAIL PROTECTED] defun
+
[EMAIL PROTECTED] 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,
[EMAIL PROTECTED] otherwise.
[EMAIL PROTECTED] defun
+
[EMAIL PROTECTED] 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
[EMAIL PROTECTED]
[EMAIL PROTECTED] defun
+
[EMAIL PROTECTED] uncaught-exception? obj
[EMAIL PROTECTED] uncaught-exception-reason exc
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] and can be accessed by calling
[EMAIL PROTECTED] on that exception. Note that
+because this exception-preservation mechanism is a side-effect of
[EMAIL PROTECTED], joining on threads that exited as described above
+but were created by other means will not raise this
[EMAIL PROTECTED] error.
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] function (@pxref{Time}). Applications wanting to
-use both will need to use a different name for one of them.
[EMAIL PROTECTED] function (@pxref{Time}) as well as the SRFI-18
[EMAIL PROTECTED] 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
