From: "Julian Graham" <joolean@gmail.com>
To: "Ludovic Courtès" <ludo@gnu.org>
Cc: guile-devel@gnu.org
Subject: Re: srfi-18 requirements
Date: Sat, 21 Jun 2008 01:03:18 -0400 [thread overview]
Message-ID: <2bc5f8210806202203w3b9e3d5dy1970898163395c2a@mail.gmail.com> (raw)
In-Reply-To: <2bc5f8210806012148o3fd3bbb4j7a5cf7b6d3baa4a7@mail.gmail.com>
[-- Attachment #1: Type: text/plain, Size: 452 bytes --]
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 <joolean@gmail.com> 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.
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-srfi-modules.texi-SRFI-18-New-sections.patch --]
[-- Type: text/x-diff; name=0001-srfi-modules.texi-SRFI-18-New-sections.patch, Size: 15571 bytes --]
From 69e05dc39167e3103171be27887529659b709b65 Mon Sep 17 00:00:00 2001
From: Julian Graham <julian@countyhell.(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
+@node SRFI-18
+@subsection SRFI-18 - Multithreading support
+@cindex SRFI-18
+
+This is an implementation of the SRFI-18 threading and synchronization
+library. The functions and variables described here are provided by
+
+@example
+(use-modules (srfi srfi-18))
+@end 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
+@code{make-mutex} 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.
+
+@menu
+* 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
+@end menu
+
+@node SRFI-18 Threads
+@subsubsection 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
+@code{make-thread} 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.
+
+@defun 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}).
+@end defun
+
+@defun 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
+@code{thread?} (@pxref{Threads}).
+@end defun
+
+@defun 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
+@var{name}, which may be any Scheme object.
+
+Note that the name @code{make-thread} conflicts with the
+@code{(ice-9 threads)} function @code{make-thread}. Applications
+wanting to use both of these functions will need to refer to them by
+different names.
+@end defun
+
+@defun 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.
+@end defun
+
+@defun thread-specific thread
+@defunx 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.
+@end defun
+
+@defun thread-start! thread
+Unblocks @var{thread} and allows it to begin execution if it has not
+done so already.
+@end defun
+
+@defun thread-yield!
+If one or more threads are waiting to execute, calling
+@code{thread-yield!} 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}.
+@end defun
+
+@defun thread-sleep! timeout
+The current thread waits until the point specified by the time object
+@var{timeout} 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}.
+@end defun
+
+@defun 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,
+@code{thread-terminate!} does not return. Otherwise
+@code{thread-terminate!} 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.
+
+@code{thread-terminate!} 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
+@code{thread-join!}.
+@end defun
+
+@defun 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,
+@var{timeoutval} is returned if it is specified; otherwise, a
+@code{join-timeout-exception} 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
+@code{uncaught-exception-reason}).
+@end defun
+
+
+@node SRFI-18 Mutexes
+@subsubsection 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:
+@itemize @bullet
+@item
+@code{recursive}: the mutex can be locked recursively
+@item
+@code{unchecked-unlock}: attempts to unlock a mutex that is already
+unlocked will not raise an exception
+@item
+@code{allow-external-unlock}: the mutex can be unlocked by any thread,
+not just the thread that locked it originally
+@end itemize
+
+@defun make-mutex [name]
+Returns a new mutex, optionally assigning it the object name
+@var{name}, which may be any Scheme object. The returned mutex will be
+created with the configuration described above. Note that the name
+@code{make-mutex} 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.
+@end defun
+
+@defun 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.
+@end defun
+
+@defun mutex-specific mutex
+@defunx 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.
+@end defun
+
+@defun mutex-state mutex
+Returns information about the state of @var{mutex}. Possible values
+are:
+@itemize @bullet
+@item
+thread @code{T}: the mutex is in the locked/owned state and thread T
+is the owner of the mutex
+@item
+symbol @code{not-owned}: the mutex is in the locked/not-owned state
+@item
+symbol @code{abandoned}: the mutex is in the unlocked/abandoned state
+@item
+symbol @code{not-abandoned}: the mutex is in the
+unlocked/not-abandoned state
+@end itemize
+@end defun
+
+@defun 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.
+@end defun
+
+@defun mutex-unlock! mutex [condition-variable [timeout]]
+Unlock @var{mutex}, optionally specifying a condition variable
+@var{condition-variable} 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
+@code{unlock-mutex} procedure in the core library.
+@end defun
+
+
+@node SRFI-18 Condition variables
+@subsubsection 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
+@code{mutex-unlock!} function described in the previous section, or
+Guile's built-in @code{wait-condition-variable} procedure can be used.
+
+@defun 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?}}).
+@end defun
+
+@defun 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.
+@end defun
+
+@defun 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.
+@end defun
+
+@defun condition-variable-specific condition-variable
+@defunx condition-variable-specific-set! condition-variable obj
+Get or set the ``object-specific'' property of
+@var{condition-variable}. In Guile's implementation of SRFI-18, this
+value is stored as an object property, and will be @code{#f} if not
+set.
+@end defun
+
+@defun condition-variable-signal! condition-variable
+@defunx 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
+@code{signal-condition-variable} and
+@code{broadcast-condition-variable} in the core library.
+@end defun
+
+
+@node SRFI-18 Time
+@subsubsection 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.
+
+@defun 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.
+@end defun
+
+@defun time? obj
+Returns @code{#t} if @var{obj} is a time object, @code{#f} otherwise.
+@end defun
+
+@defun time->seconds time
+@defunx 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
+@var{time} and the epoch. When converting from seconds to a time
+object, the return value is a time object that represents a time
+@var{seconds} seconds after the epoch.
+@end defun
+
+
+@node SRFI-18 Exceptions
+@subsubsection 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''.
+
+@defun current-exception-handler
+Returns the current exception handler.
+@end defun
+
+@defun 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.
+@end defun
+
+@defun raise obj
+Raise @var{obj} as an exception. This is the same procedure as the
+same-named procedure defined in SRFI 34.
+@end defun
+
+@defun 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.
+@end defun
+
+@defun 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,
+@code{#f} otherwise.
+@end defun
+
+@defun 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
+@code{thread-terminate!}.
+@end defun
+
+@defun uncaught-exception? obj
+@defunx uncaught-exception-reason exc
+@code{uncaught-exception?} 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
+@code{thread-join!} and can be accessed by calling
+@code{uncaught-exception-reason} on that exception. Note that
+because this exception-preservation mechanism is a side-effect of
+@code{make-thread}, joining on threads that exited as described above
+but were created by other means will not raise this
+@code{uncaught-exception} error.
+@end 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
-@code{current-time} function (@pxref{Time}). Applications wanting to
-use both will need to use a different name for one of them.
+@code{current-time} function (@pxref{Time}) as well as the SRFI-18
+@code{current-time} 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
next prev parent reply other threads:[~2008-06-21 5:03 UTC|newest]
Thread overview: 75+ messages / expand[flat|nested] mbox.gz Atom feed top
2007-10-11 1:54 srfi-18 requirements Julian Graham
2007-10-12 8:42 ` Ludovic Courtès
2007-10-12 15:31 ` Julian Graham
2007-10-15 22:26 ` Julian Graham
2007-10-15 22:35 ` Stephen Compall
2007-10-15 22:47 ` Julian Graham
2007-10-29 14:37 ` Julian Graham
2007-11-26 18:11 ` Julian Graham
2007-11-27 9:14 ` Ludovic Courtès
2007-11-28 18:23 ` Ludovic Courtès
2007-11-28 18:55 ` Julian Graham
2007-12-01 5:08 ` Julian Graham
2007-12-01 10:21 ` Ludovic Courtès
2007-12-02 3:59 ` Julian Graham
2007-12-04 22:20 ` Neil Jerram
2007-12-04 22:29 ` Neil Jerram
2007-12-11 4:20 ` Julian Graham
2007-12-18 4:30 ` Julian Graham
2007-12-28 18:46 ` Ludovic Courtès
2007-12-28 19:08 ` Julian Graham
2007-12-28 22:35 ` Neil Jerram
2007-12-30 11:04 ` Neil Jerram
2007-12-30 20:38 ` Julian Graham
2008-01-01 19:09 ` Neil Jerram
2008-01-04 5:01 ` Julian Graham
2008-01-05 0:30 ` Neil Jerram
2008-01-06 21:41 ` Julian Graham
2008-01-08 23:11 ` Neil Jerram
2008-01-11 2:39 ` Julian Graham
2008-01-17 1:48 ` Neil Jerram
2008-01-19 20:10 ` Julian Graham
2008-01-23 22:46 ` Neil Jerram
2008-01-23 23:23 ` Julian Graham
2008-01-25 1:07 ` Neil Jerram
2008-01-25 1:38 ` Julian Graham
2008-01-28 2:06 ` Julian Graham
2008-02-03 0:30 ` Neil Jerram
2008-02-05 6:27 ` Julian Graham
2008-02-07 1:23 ` Neil Jerram
2008-02-07 3:06 ` Julian Graham
2008-02-07 23:26 ` Neil Jerram
2008-02-07 23:33 ` Julian Graham
2008-02-07 23:38 ` Neil Jerram
2008-02-08 0:04 ` Julian Graham
2008-02-11 5:14 ` Julian Graham
2008-02-19 22:48 ` Neil Jerram
2008-02-20 2:10 ` Julian Graham
2008-02-22 0:33 ` Neil Jerram
2008-02-22 4:14 ` Julian Graham
2008-02-24 9:41 ` Neil Jerram
2008-02-24 18:17 ` Julian Graham
2008-02-24 23:29 ` Neil Jerram
2008-03-01 19:56 ` Julian Graham
2008-03-08 16:34 ` Neil Jerram
2008-03-11 4:02 ` Julian Graham
2008-03-22 18:55 ` Julian Graham
2008-03-23 23:57 ` Neil Jerram
2008-03-24 22:03 ` Neil Jerram
2008-03-26 15:55 ` Julian Graham
2008-04-03 0:18 ` Neil Jerram
2008-04-03 19:07 ` Julian Graham
2008-04-09 21:29 ` Neil Jerram
2008-04-14 0:43 ` Julian Graham
2008-05-14 1:23 ` Julian Graham
2008-05-14 21:13 ` Neil Jerram
2008-05-14 23:11 ` Neil Jerram
2008-05-15 5:05 ` Julian Graham
2008-05-24 11:42 ` Neil Jerram
2008-05-24 13:55 ` Neil Jerram
2008-05-25 2:07 ` Julian Graham
2008-05-31 21:41 ` Ludovic Courtès
2008-06-02 4:48 ` Julian Graham
2008-06-21 5:03 ` Julian Graham [this message]
2008-06-30 17:51 ` Ludovic Courtès
2008-01-08 23:41 ` Neil Jerram
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/guile/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=2bc5f8210806202203w3b9e3d5dy1970898163395c2a@mail.gmail.com \
--to=joolean@gmail.com \
--cc=guile-devel@gnu.org \
--cc=ludo@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).