Re: srfi-18 requirements

[Julian Graham]

Hi Guilers,

  Find attached a first draft of a patch to add SRFI-18 support to
Guile.  The patch contains the necessary modifications to Guile's C
code to support SRFI-18, which is provided as a Scheme module (also
attached). I don't believe any breaking changes to the API are
introduced by this code, and, in general, the only behavior that is
significantly different is that which was previously "unspecified" or
of dubious correctness -- e.g., unlocking mutexes from outside the
threads that originally locked them, or leaving abandoned mutexes
locked forever.

  I realize this is kind of a big patch, so I've included some, uh,
commentary to help you guys sift through it.  I'm working on updating
the Texinfo documentation, but didn't want to wait to submit, as the
scope and content of this patch could conceivably change. I'm also
attaching some test code that might be helpful in illustrating some of
the concepts involved in SRFI-18. Of course, I also encourage everyone
to take a look at the SRFI itself, which is available at
http://srfi.schemers.org/srfi-18/srfi-18.html.

  Please let me know if you have any questions / comments!


Best Regards,
Julian


SIGNIFICANT CHANGES TO THREADS.H
================================

* Three members have been added to the thread data structure:

** admin_mutex, which is a lighter-weight version of the
thread_admin_mutex, which should be used instead of thread_admin_mutex
in situations requiring synchronous access to thread-specific
information, such as checking whether a thread has been marked exited,
that do not require access to the global list of threads

** mutexes, a SCM list of mutexes owned by a thread.  This is
necessary so that threads waiting on mutexes that an exiting thread is
abandoning can be notified

** exception, a SCM holding any uncaught exceptions thrown by the
thread or its cleanup handler.  We need this so we can deliver
uncaught exceptions to threads that join on a terminated thread


NEW C FUNCTIONS
===============

* scm_join_thread_timed (t, timeout, timeout_val): An overload of
scm_join_thread featuring extended timeout semantics from SRFI-18
* scm_thread_p (obj): A type predicate for threads
* scm_lock_mutex_timed (m, abstime, thread): An overload of
scm_lock_mutex featuring extended timeout and ownership semantics from
SRFI-18
* scm_unlock_mutex_timed (m, cond, abstime): An overload of
scm_unlock_mutex featuring extended timeout semantics from SRFI-18
* scm_mutex_state (m): Mutex state reporting from SRFI-18
* scm_mutex_p (obj): A type predicate for mutexes
* scm_condition_variable_p (obj): A type predicate for condition variables


NEW SCHEME FUNCTIONS (without loading SRFI-18)
==============================================

* join-thread thread -> join-thread thread [timeout [timeoutval]]
* thread? obj
* lock-mutex mutex -> lock-mutex mutex [timeout [owner]]
* unlock-mutex mutex -> unlock-mutex mutex [cond [timeout]]
* mutex-state mutex
* mutex? obj
* condition-variable? obj


SIGNIFICANT CHANGES TO THREADS.C
================================

* A static function, scm_to_timespec, has been added to thread.c that
converts SCM timeouts -- either in numerical form or as (secs . usecs)
-- to an scm_t_timespec

* Because the owner of a locked mutex can be #f, unblock_from_queue
now returns SCM_UNDEFINED when a queue is empty, in order to avoid
ambiguity.  This is purely for consistency -- #f cannot actually be
added to a queue

* The catch calls in do_thread_exit and really_launch now include a
handler (if the caller does not specify one already),
exception_preserve_catch_handler, which saves exception data in the
thread's exception field

* scm_join_thread, which now calls scm_join_thread_timed, will rethrow
any uncaught exceptions thrown by the terminated thread

* fat_mutex_lock and fat_mutex_unlock now add and remove mutexes from
a thread's list of locked mutexes. As part of thread exit, other
threads waiting on mutexes in this list are woken up

* An unlocked fat_mutex now has its owner set to SCM_UNDEFINED, not SCM_BOOL_F

* fat_mutex_lock has been largely rewritten (although the behavior is
almost exactly the same for calls that do not specify a timeout) in
order to deal with SRFI-18's concept of mutex states. It is now a loop
that synchronously inspects the current state of the mutex to
determine whether it can be locked, sleeping on the mutex's condition
variable if it cannot be. As per SRFI-18, an attempt to lock an
abandoned mutex will succeed, although an abandoned-mutex-exception
will be thrown. fat_mutex_lock now returns an exception instead of a
char *, indicating the success of the lock via a passed-in int
pointer.

* fat_mutex_unlock now allows a mutex to be unlocked from any thread,
as per SRFI-18


SIGNIFICANT CHANGES TO SCMSIGS.C
================================

* The scm_spawn_thread call that launches the signal delivery thread
no longer specifies a handler. No one should call scm_spawn_thread
with a handler, because of an already-present deadlock in 1.8.x -- in
a multithreaded context, a guile mode thread (i.e., one that has
locked its heap mutex) may attempt to enter a critical section in
eval.i.c at the same time a non-guile mode thread created by
scm_spawn_thread is within a critical section in make_jmpbuf while
setting up a catch handler and attempts to do a GC

srfi-18.HEAD.patch
Description: Text Data

srfi-18.scm
Description: Text Data

srfi-18.test
Description: Binary data