Changes between Version 2 and Version 3 of Concurrency/DraftReportText

Timestamp:

01/16/07 04:59:52 (6 years ago)

Author:

simonmar@…

Comment:

add bound threads text

Concurrency/DraftReportText

@@ -2 +2 @@
 = Draft Chapter: Concurrency =
 
-Haskell supports ''concurrency'', in the sense that a program can contain multiple threads of execution interacting non-deterministically.  Precisely what we mean by this, and what guarantees the programmer is given, are described in the following chapter.  The material here is to be read concurrently with the description of the `Control.Concurrent` library, in Chapter ??.
+Haskell supports ''concurrency'', in the sense that a program can contain multiple threads of execution interacting non-deterministically.  Precisely what we mean by this, and what guarantees the programmer is given, are described in this chapter.  The material here is to be read concurrently with the description of the `Control.Concurrent` library, in Chapter ??.
 
 == Threads ==
@@ -16 +16 @@
 Operations performed by multiple threads may be interleaved arbitrarily by the implementation, with the following restriction:
 
- * A thread that is not blocked on a resource will not be indefinitely delayed by the implementation.
+ * A thread that is not ''blocked'' will not be indefinitely delayed by the implementation.
+
+Where a thread is ''blocked'' if
+
+ * the thread is waiting for an external resource that is currently not available (for example input
+   from the console), or it is performing an operation that involves a shared resource and another thread
+   currently has ownership of the resource (for example, output to a `Handle`).
 
 This is called the ''fairness guarantee''.  An implementation technique that is often used to provide this fairness guarnatee is ''pre-emption'': running threads are periodically pre-empted in software in order to let other threads proceed.  There are other implementation techniques that also work; for example, hardware concurrency.  ('''ToDo''': move this text to a footnote or separate section?)
 
-'''ToDo''': explain "blocking".
 
 == The `ThreadId` type ==
@@ -66 +71 @@
 '''ToDo'''.
 
-Bound threads allow a Haskell program more control over the mapping between Haskell threads and OS threads.  Such control is required for interacting with foreign code that is either single-threaded or makes use of thread-local state in the native OS threading model.
+Bound threads allow a Haskell program more control over the mapping between Haskell threads and OS threads.  Such control is required for interacting with foreign code that makes use of thread-local state in the native OS threading model.  When foreign code uses OS thread-local state, the Haskell programmer needs to restrict calls to that foreign code to happen in a particular OS thread, which is what bound threads provide.
+
+Bound threads are an optional feature in Haskell'; the documentation for an implementation should state whether bound threads are supported or not.
+
+A Haskell thread can be either ''bound'' or ''unbound'', depending on how it was created:
+
+ * Calls from foreign code to Haskell functions exposed by `foreign export` or `foreign import "wrapper"` create a
+   ''bound'' thread in which to run the computation.
+
+ * `forkIO` creates ''unbound'' threads
+
+Whether a thread is bound or unbound affects how foreign calls are made:
+
+  * Foreign calls made by an unbound thread happen in an arbitrary OS thread.
+
+  * Foreign calls made by a bound thread are always made by the OS thread that made the original call-in.
+
+Note that a valid implementation of bound threads is one in which every Haskell thread is associated with a distinct OS thread, where in effect every thread is bound.  However, the `isCurrentThreadBound` operation (see below) should always return `False` for threads created by `forkIO`, regardless of the implementation, to aid portabilty.
+
+The following operations exported by `Control.Concurrent` are related to bound threads:
+
+{{{
+  supportsBoundThreads :: Bool
+}}}
+
+This value is `True` if the implementation supports bound threads ('''NB.''' this is called `rtsSupportsBoundThreads` currently).
+
+{{{
+  isCurrentThreadBound :: IO Bool
+}}}
+
+This operation returns `False` if the current thread was created by `forkIO`, and `True` otherwise.
+
+{{{
+  forkOS :: IO () -> IO ThreadId
+}}}
+
+Like `forkIO`, `forkOS` creates a new Haskell thread to run the supplied `IO` action.  However, in the case of `forkOS`, the new Haskell thread is bound to a freshly created OS thread.  This is achieved by making a foreign call to create the new OS thread, and having the new OS thread invoke the `IO` action, thus creating a bound thread.