doc threads concurrency

doc threads concurrency

[Kevin Ryde]

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

This attempts to describe the situation in the current head,

        * scheme-scheduling.texi (Threads): Note Guile uses POSIX threads, for
        concurrency and preemption.
        (C level thread interface): Note periodic libguile call required for C
        code in threads, add commented out reminders for SCM_TICK and
        guile-mode, for when those features are ready.

Incidentally, I'd be a bit tempted at some stage to have mutexes and
condition variables in sections of their own, with scheme and C
described together.  Which might leave "C level thread interface" as
just the C level thread creation and rules for operating.


[-- Attachment #2: scheme-scheduling.texi.threads.diff --]
[-- Type: text/plain, Size: 3003 bytes --]

--- scheme-scheduling.texi.~1.14.~	2003-07-24 10:12:43.000000000 +1000
+++ scheme-scheduling.texi	2003-12-05 09:24:37.000000000 +1000
@@ -280,21 +280,12 @@
 @section Threads
 @cindex threads
 @cindex Guile threads
+@cindex POSIX threads
 
-@strong{[NOTE: this chapter was written for Cygnus Guile and has not yet
-been updated for the Guile 1.x release.]}
-
-Here is a the reference for Guile's threads.  In this chapter I simply
-quote verbatim Tom Lord's description of the low-level primitives
-written in C (basically an interface to the POSIX threads library) and
-Anthony Green's description of the higher-level thread procedures
-written in scheme.
-@cindex posix threads
-@cindex Lord, Tom
-@cindex Green, Anthony
-
-When using Guile threads, keep in mind that each guile thread is
-executed in a new dynamic root.
+Guile threads are implemented using POSIX threads, they run
+pre-emptively and concurrently through both Scheme code and system
+calls.  The only exception is for garbage collection, where all
+threads must rendezvous.
 
 @menu
 * Low level thread primitives::  
@@ -450,6 +441,43 @@
 higher level threads.  By reimplementing them, you can adapt Guile to
 different low-level thread implementations.
 
+C code in a thread must call a libguile function periodically.  When
+one thread finds garbage collection is required, it waits for all
+threads to rendezvous before doing that gc.  Such a rendezvous is
+checked within libguile functions.  If C code wants to sleep or block
+in a thread it should use one of the libguile functions provided.
+
+Only threads created by Guile can use the libguile functions.  Threads
+created directly with say @code{pthread_create} are unknown to Guile
+and they cannot call libguile.  The stack in such foreign threads is
+not scanned during GC, so @code{SCM} values generally cannot be held
+there.
+
+@c  FIXME:
+@c
+@c  Describe SCM_TICK which can be called if no other libguile
+@c  function is being used by a C function.
+@c
+@c  Describe "Guile mode", which a thread can enter and exit.  There
+@c  are no functions for doing this yet.
+@c
+@c  When in guile mode a thread can call libguile, is subject to the
+@c  tick rule, and its stack is scanned.  When not in guile mode it
+@c  cannot call libguile, it doesn't have to tick, and its stack is
+@c  not scanned.  The strange guile control flow things like
+@c  exceptions, continuations and asyncs only occur when in guile
+@c  mode.
+@c
+@c  When guile mode is exited, the portion of the stack allocated
+@c  while it was in guile mode is still scanned.  This portion may not
+@c  be modified when outside guile mode.  The stack ends up
+@c  partitioned into alternating guile and non-guile regions.
+@c
+@c  Leaving guile mode is convenient when running an extended
+@c  calculation not involving guile, since one doesn't need to worry
+@c  about SCM_TICK calls.
+
+
 @deftp {C Data Type} scm_t_thread
 This data type represents a thread, to be used with scm_thread_create,
 etc.

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

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