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