+++ /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>