Fix more documentation wibbles
[ghc.git] / docs / users_guide / using-concurrent.rst
1 .. _using-concurrent:
2
3 Using Concurrent Haskell
4 ------------------------
5
6 .. index::
7    single: Concurrent Haskell; using
8
9 GHC supports Concurrent Haskell by default, without requiring a special
10 option or libraries compiled in a certain way. To get access to the
11 support libraries for Concurrent Haskell, just import
12 :base-ref:`Control.Concurrent <Control-Concurrent.html>`.
13 More information on Concurrent Haskell is provided in the documentation
14 for that module.
15
16 Optionally, the program may be linked with the :ghc-flag:`-threaded` option (see
17 :ref:`options-linker`. This provides two benefits:
18
19 - It enables the :rts-flag:`-N ⟨x⟩` to be used, which allows threads to run in
20   parallelism on a multi-processor or multi-core machine. See :ref:`using-smp`.
21
22 - If a thread makes a foreign call (and the call is not marked
23   ``unsafe``), then other Haskell threads in the program will continue
24   to run while the foreign call is in progress. Additionally,
25   ``foreign export``\ ed Haskell functions may be called from multiple
26   OS threads simultaneously. See :ref:`ffi-threads`.
27
28 The following RTS option(s) affect the behaviour of Concurrent Haskell
29 programs:
30
31 .. index::
32    single: RTS options; concurrent
33
34 .. rts-flag:: -C ⟨s⟩
35
36     :default: 20 milliseconds
37
38     Sets the context switch interval to ⟨s⟩ seconds.
39     A context switch will occur at the next heap block allocation after
40     the timer expires (a heap block allocation occurs every 4k of
41     allocation). With ``-C0`` or ``-C``, context switches will occur as
42     often as possible (at every heap block allocation).
43
44 .. _using-smp:
45
46 Using SMP parallelism
47 ---------------------
48
49 .. index::
50    single: parallelism
51    single: SMP
52
53 GHC supports running Haskell programs in parallel on an SMP (symmetric
54 multiprocessor).
55
56 There's a fine distinction between *concurrency* and *parallelism*:
57 parallelism is all about making your program run *faster* by making use
58 of multiple processors simultaneously. Concurrency, on the other hand,
59 is a means of abstraction: it is a convenient way to structure a program
60 that must respond to multiple asynchronous events.
61
62 However, the two terms are certainly related. By making use of multiple
63 CPUs it is possible to run concurrent threads in parallel, and this is
64 exactly what GHC's SMP parallelism support does. But it is also possible
65 to obtain performance improvements with parallelism on programs that do
66 not use concurrency. This section describes how to use GHC to compile
67 and run parallel programs, in :ref:`lang-parallel` we describe the
68 language features that affect parallelism.
69
70 .. _parallel-compile-options:
71
72 Compile-time options for SMP parallelism
73 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
74
75 In order to make use of multiple CPUs, your program must be linked with
76 the :ghc-flag:`-threaded` option (see :ref:`options-linker`). Additionally, the
77 following compiler options affect parallelism:
78
79 .. ghc-flag:: -feager-blackholing
80
81     Blackholing is the act of marking a thunk (lazy computation) as
82     being under evaluation. It is useful for three reasons: firstly it
83     lets us detect certain kinds of infinite loop (the
84     ``NonTermination`` exception), secondly it avoids certain kinds of
85     space leak, and thirdly it avoids repeating a computation in a
86     parallel program, because we can tell when a computation is already
87     in progress.
88
89     The option :ghc-flag:`-feager-blackholing` causes each thunk to be
90     blackholed as soon as evaluation begins. The default is "lazy
91     blackholing", whereby thunks are only marked as being under
92     evaluation when a thread is paused for some reason. Lazy blackholing
93     is typically more efficient (by 1-2% or so), because most thunks
94     don't need to be blackholed. However, eager blackholing can avoid
95     more repeated computation in a parallel program, and this often
96     turns out to be important for parallelism.
97
98     We recommend compiling any code that is intended to be run in
99     parallel with the :ghc-flag:`-feager-blackholing` flag.
100
101 .. _parallel-options:
102
103 RTS options for SMP parallelism
104 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
105
106 There are two ways to run a program on multiple processors: call
107 :base-ref:`Control.Concurrent.setNumCapabilities
108 <Control.Concurrent.html#v:setNumCapabilities>` from your program, or
109 use the RTS :rts-flag:`-N ⟨x⟩` options.
110
111 .. rts-flag:: -N ⟨x⟩
112               -maxN ⟨x⟩
113
114     Use ⟨x⟩ simultaneous threads when running the program.
115
116     The runtime manages a set of virtual processors, which we call
117     *capabilities*, the number of which is determined by the ``-N``
118     option. Each capability can run one Haskell thread at a time, so the
119     number of capabilities is equal to the number of Haskell threads
120     that can run physically in parallel. A capability is animated by one
121     or more OS threads; the runtime manages a pool of OS threads for
122     each capability, so that if a Haskell thread makes a foreign call
123     (see :ref:`ffi-threads`) another OS thread can take over that
124     capability.
125
126     Normally ⟨x⟩ should be chosen to match the number of CPU cores on
127     the machine [1]_. For example, on a dual-core machine we would
128     probably use ``+RTS -N2 -RTS``.
129
130     Omitting ⟨x⟩, i.e. ``+RTS -N -RTS``, lets the runtime choose the
131     value of ⟨x⟩ itself based on how many processors are in your
132     machine.
133
134     With ``-maxN⟨x⟩``, i.e. ``+RTS -maxN3 -RTS``, the runtime will choose
135     at most (x), also limited by the number of processors on the system.
136     Omitting (x) is an error, if you need a default use option ``-N``.
137
138     Be careful when using all the processors in your machine: if some of
139     your processors are in use by other programs, this can actually harm
140     performance rather than improve it. Asking GHC to create more capabilities
141     than you have physical threads is almost always a bad idea.
142
143     Setting ``-N`` also has the effect of enabling the parallel garbage
144     collector (see :ref:`rts-options-gc`).
145
146     The current value of the ``-N`` option is available to the Haskell
147     program via ``Control.Concurrent.getNumCapabilities``, and it may be
148     changed while the program is running by calling
149     ``Control.Concurrent.setNumCapabilities``.
150
151 The following options affect the way the runtime schedules threads on
152 CPUs:
153
154 .. rts-flag:: -qa
155
156     Use the OS's affinity facilities to try to pin OS threads to CPU
157     cores.
158
159     When this option is enabled, the OS threads for a capability :math:`i` are
160     bound to the CPU core :math:`i` using the API provided by the OS for setting
161     thread affinity. e.g. on Linux GHC uses ``sched_setaffinity()``.
162
163     Depending on your workload and the other activity on the machine,
164     this may or may not result in a performance improvement. We
165     recommend trying it out and measuring the difference.
166
167 .. rts-flag:: -qm
168
169     Disable automatic migration for load balancing. Normally the runtime
170     will automatically try to schedule threads across the available CPUs
171     to make use of idle CPUs; this option disables that behaviour. Note
172     that migration only applies to threads; sparks created by ``par``
173     are load-balanced separately by work-stealing.
174
175     This option is probably only of use for concurrent programs that
176     explicitly schedule threads onto CPUs with
177     :base-ref:`Control.Concurrent.forkOn <Control-Concurrent.html#v:forkOn>`.
178
179 Hints for using SMP parallelism
180 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
181
182 Add the :rts-flag:`-s [⟨file⟩]` RTS option when running the program to see
183 timing stats, which will help to tell you whether your program got faster by
184 using more CPUs or not. If the user time is greater than the elapsed time, then
185 the program used more than one CPU. You should also run the program without
186 :rts-flag:`-N ⟨x⟩` for comparison.
187
188 The output of ``+RTS -s`` tells you how many "sparks" were created and
189 executed during the run of the program (see :ref:`rts-options-gc`),
190 which will give you an idea how well your ``par`` annotations are
191 working.
192
193 GHC's parallelism support has improved in 6.12.1 as a result of much
194 experimentation and tuning in the runtime system. We'd still be
195 interested to hear how well it works for you, and we're also interested
196 in collecting parallel programs to add to our benchmarking suite.
197
198 .. [1] Whether hyperthreading cores should be counted or not is an open
199        question; please feel free to experiment and let us know what results you
200        find.