This section of the commentary explains the structure of the runtime system + when used in threaded or SMP mode.
+ +The threaded version of the runtime supports + bound threads and non-blocking foreign calls, and an overview of its + design can be found in the paper Extending + the Haskell Foreign Function Interface with Concurrency. To + compile the runtime with threaded support, add the line + +
GhcRTSWays += thr+ + to mk/build.mk. When building C code in the runtime for the threaded way, + the symbol THREADED_RTS is defined (this is arranged by the + build system when building for way thr, see + mk/config.mk). To build a Haskell program + with the threaded runtime, pass the flag -threaded to GHC (this + can be used in conjunction with -prof, and possibly + -debug and others depending on which versions of the RTS have + been built. + +
The SMP 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 + +
+GhcRTSWays += thr +GhcLibWays += s+ + to mk/build.mk. To build Haskell code for + SMP execution, use the flag -smp to GHC (this can be used in + conjunction with -debug, but no other way-flags at this time). + When building C code in the runtime for SMP + support, the symbol SMP is defined (this is arranged by the + compiler when the -smp flag is given, see + ghc/compiler/main/StaticFlags.hs). + +
When building the runtime in either the threaded or SMP ways, the symbol + RTS_SUPPORTS_THREADS will be defined (see Rts.h).
+ +The system is based around the notion of a Capability. A + Capability 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 + Capability. The available pool of capabilities is managed by + the Capability API, described below.
+ +In the threaded runtime, there is only a single Capabililty 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 +RTS -Nn + flag; in practice the number is best chosen to be the same as the number of + processors on the host machine.
+ +There are a number of OS threads running code in the runtime. We call + these tasks to avoid confusion with Haskell threads. + Tasks are managed by the Task 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.
+ +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 bound thread, as described in the FFI/Concurrency paper (cited + above).
+ +In the future we may want to bind a Capability 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.
+ +This interface is merely an abstraction layer over the OS-specific APIs + for managing threads. It has two main implementations: Win32 and + POSIX.
+ +This is the entirety of the interface:
+ ++/* 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 ); ++ +