Re: thread cancellation, take 2

["Julian Graham" <joolean@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 459 bytes --]

Find attached a patch that adds documentation for the thread
cancellation functions.  Let me know if I should change anything.


On 10/23/07, Julian Graham <joolean@gmail.com> wrote:
> > Actually, condition variables and mutexes seem to be fairly well
> > documented, or did I miss something else?  :-)
>
>
> Oops, for some reason I was looking at the 1.6.8 manual (blame it on
> the cold I've had for the past few days).  I'll have some docs in
> shortly.
>

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: thread-cancellation-doc.HEAD.patch --]
[-- Type: text/x-patch; name=thread-cancellation-doc.HEAD.patch, Size: 2538 bytes --]

Index: api-scheduling.texi
===================================================================
RCS file: /sources/guile/guile/guile-core/doc/ref/api-scheduling.texi,v
retrieving revision 1.17
diff -a -u -r1.17 api-scheduling.texi
--- api-scheduling.texi	17 Jun 2006 23:15:22 -0000	1.17
+++ api-scheduling.texi	24 Oct 2007 02:29:46 -0000
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
-@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004
+@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007
 @c   Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
@@ -285,6 +285,42 @@
 immediate context switch to one of them. Otherwise, yield has no effect.
 @end deffn
 
+@deffn {Scheme Procedure} cancel-thread thread
+@deffnx {C Function} scm_cancel_thread (thread)
+Asynchronously notify @code{thread} to exit. Immediately after receiving
+this notification, @code{thread} will call its cleanup handler (if one
+has been set) and then terminate, aborting any evaluation that is in
+progress.
+
+Because Guile threads are isomorphic with POSIX threads, @code{thread}
+will not receive its cancellation signal until it reaches a cancellation
+point. See your operating system's POSIX threading documentation for 
+more information on cancellation points; note that in Guile, unlike 
+native POSIX threads, a thread can receive a cancellation notification 
+while attempting to lock a mutex. 
+@end deffn
+
+@deffn {Scheme Procedure} set-thread-cleanup! thread proc
+@deffnx {C Function} scm_set_thread_cleanup_x (thread, proc)
+Set @code{proc} as the cleanup handler for the thread @code{thread}.
+@code{proc}, which must be a thunk, will be called when @code{thread} 
+exits, either normally or by being canceled. Thread cleanup handlers
+can be used to perform useful tasks like releasing resources, such as
+locked mutexes, when thread exit cannot be predicted.
+
+The return value of @var{proc} will be set as the @emph{exit value} of
+@code{thread}.
+
+To remove a cleanup handler, pass @code{#f} for @code{proc}.
+@end deffn
+
+@deffn {Scheme Procedure} thread-cleanup thread
+@deffnx {C Function} scm_thread_cleanup (thread)
+Return the cleanup handler currently installed for the thread 
+@code{thread}. If no cleanup handler is currently installed, 
+thread-cleanup returns @code{#f}.
+@end deffn
+
 Higher level thread procedures are available by loading the
 @code{(ice-9 threads)} module.  These provide standardized
 thread creation.

[-- Attachment #3: Type: text/plain, Size: 143 bytes --]

_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel