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 <[EMAIL PROTECTED]> 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.
>
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.
[EMAIL PROTECTED] Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] {Scheme Procedure} cancel-thread thread
[EMAIL PROTECTED] {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.
[EMAIL PROTECTED] deffn
+
[EMAIL PROTECTED] {Scheme Procedure} set-thread-cleanup! thread proc
[EMAIL PROTECTED] {C Function} scm_set_thread_cleanup_x (thread, proc)
+Set @code{proc} as the cleanup handler for the thread @code{thread}.
[EMAIL PROTECTED], 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
[EMAIL PROTECTED]
+
+To remove a cleanup handler, pass @code{#f} for @code{proc}.
[EMAIL PROTECTED] deffn
+
[EMAIL PROTECTED] {Scheme Procedure} thread-cleanup thread
[EMAIL PROTECTED] {C Function} scm_thread_cleanup (thread)
+Return the cleanup handler currently installed for the thread
[EMAIL PROTECTED] If no cleanup handler is currently installed,
+thread-cleanup returns @code{#f}.
[EMAIL PROTECTED] deffn
+
Higher level thread procedures are available by loading the
@code{(ice-9 threads)} module. These provide standardized
thread creation.
_______________________________________________
Guile-devel mailing list
[email protected]
http://lists.gnu.org/mailman/listinfo/guile-devel
