--- /dev/null
+<html>
+ <head>
+ <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
+ <title>The GHC Commentary - The Multi-threaded runtime, and multiprocessor execution</title>
+ </head>
+
+ <body>
+ <h1>The GHC Commentary - The Multi-threaded runtime, and multiprocessor execution</h1>
+
+ <p>This section of the commentary explains the structure of the runtime system
+ when used in threaded or SMP mode.</p>
+
+ <p>The <em>threaded</em> version of the runtime supports
+ bound threads and non-blocking foreign calls, and an overview of its
+ design can be found in the paper <a
+ href="http://www.haskell.org/~simonmar/papers/conc-ffi.pdf">Extending
+ the Haskell Foreign Function Interface with Concurrency</a>. To
+ compile the runtime with threaded support, add the line
+
+<pre>GhcRTSWays += thr</pre>
+
+ to <tt>mk/build.mk</tt>. When building C code in the runtime for the threaded way,
+ the symbol <tt>THREADED_RTS</tt> is defined (this is arranged by the
+ build system when building for way <tt>thr</tt>, see
+ <tt>mk/config.mk</tt>). To build a Haskell program
+ with the threaded runtime, pass the flag <tt>-threaded</tt> to GHC (this
+ can be used in conjunction with <tt>-prof</tt>, and possibly
+ <tt>-debug</tt> and others depending on which versions of the RTS have
+ been built.</p>
+
+ <p>The <em>SMP</em> version runtime supports the same facilities as the
+ threaded version, and in addition supports execution of Haskell code by
+ multiple simultaneous OS threads. For SMP support, both the runtime and
+ the libraries must be built a special way: add the lines
+
+ <pre>
+GhcRTSWays += thr
+GhcLibWays += s</pre>
+
+ to <tt>mk/build.mk</tt>. To build Haskell code for
+ SMP execution, use the flag <tt>-smp</tt> to GHC (this can be used in
+ conjunction with <tt>-debug</tt>, but no other way-flags at this time).
+ When building C code in the runtime for SMP
+ support, the symbol <tt>SMP</tt> is defined (this is arranged by the
+ compiler when the <tt>-smp</tt> flag is given, see
+ <tt>ghc/compiler/main/StaticFlags.hs</tt>).</p>
+
+ <p>When building the runtime in either the threaded or SMP ways, the symbol
+ <tt>RTS_SUPPORTS_THREADS</tt> will be defined (see <tt>Rts.h</tt>).</p>
+
+ <h2>Overall design</h2>
+
+ <p>The system is based around the notion of a <tt>Capability</tt>. A
+ <tt>Capability</tt> is an object that represents both the permission to
+ execute some Haskell code, and the state required to do so. In order
+ to execute some Haskell code, a thread must therefore hold a
+ <tt>Capability</tt>. The available pool of capabilities is managed by
+ the <tt>Capability</tt> API, described below.</p>
+
+ <p>In the threaded runtime, there is only a single <tt>Capabililty</tt> in the
+ system, indicating that only a single thread can be executing Haskell
+ code at any one time. In the SMP runtime, there can be an arbitrary
+ number of capabilities selectable at runtime with the <tt>+RTS -N<em>n</em></tt>
+ flag; in practice the number is best chosen to be the same as the number of
+ processors on the host machine.</p>
+
+ <p>There are a number of OS threads running code in the runtime. We call
+ these <em>tasks</em> to avoid confusion with Haskell <em>threads</em>.
+ Tasks are managed by the <tt>Task</tt> subsystem, which is mainly
+ concerned with keeping track of statistics such as how much time each
+ task spends executing Haskell code, and also keeping track of how many
+ tasks are around when we want to shut down the runtime.</p>
+
+ <p>Some tasks are created by the runtime itself, and some may be here
+ as a result of a call to Haskell from foreign code (we
+ call this an in-call). The
+ runtime can support any number of concurrent foreign in-calls, but the
+ number of these calls that will actually run Haskell code in parallel is
+ determined by the number of available capabilities. Each in-call creates
+ a <em>bound thread</em>, as described in the FFI/Concurrency paper (cited
+ above).</p>
+
+ <p>In the future we may want to bind a <tt>Capability</tt> to a particular
+ processor, so that we can support a notion of affinity - avoiding
+ accidental migration of work from one CPU to another, so that we can make
+ best use of a CPU's local cache. For now, the design ignores this
+ issue.</p>
+
+ <h2>The <tt>OSThreads</tt> interface</h2>
+
+ <p>This interface is merely an abstraction layer over the OS-specific APIs
+ for managing threads. It has two main implementations: Win32 and
+ POSIX.</p>
+
+ <p>This is the entirety of the interface:</p>
+
+<pre>
+/* Various abstract types */
+typedef Mutex;
+typedef Condition;
+typedef OSThreadId;
+
+extern OSThreadId osThreadId ( void );
+extern void shutdownThread ( void );
+extern void yieldThread ( void );
+extern int createOSThread ( OSThreadId* tid,
+ void (*startProc)(void) );
+
+extern void initCondition ( Condition* pCond );
+extern void closeCondition ( Condition* pCond );
+extern rtsBool broadcastCondition ( Condition* pCond );
+extern rtsBool signalCondition ( Condition* pCond );
+extern rtsBool waitCondition ( Condition* pCond,
+ Mutex* pMut );
+
+extern void initMutex ( Mutex* pMut );
+ </pre>
+
+ <h2>The Task interface</h2>
+
+ <h2>The Capability interface</h2>
+
+ <h2>Multiprocessor Haskell Execution</h2>
+
+ </body>
+</html>
projects / ghc-hetmet.git / blobdiff