diff options
Diffstat (limited to 'docs/users_guide/using-concurrent.rst')
| -rw-r--r-- | docs/users_guide/using-concurrent.rst | 50 |
1 files changed, 23 insertions, 27 deletions
diff --git a/docs/users_guide/using-concurrent.rst b/docs/users_guide/using-concurrent.rst index b2b235ad3e..c5179c7333 100644 --- a/docs/users_guide/using-concurrent.rst +++ b/docs/users_guide/using-concurrent.rst @@ -13,19 +13,17 @@ support libraries for Concurrent Haskell, just import More information on Concurrent Haskell is provided in the documentation for that module. -Optionally, the program may be linked with the ``-threaded`` option (see +Optionally, the program may be linked with the :ghc-flag:`-threaded` option (see :ref:`options-linker`. This provides two benefits: -- It enables the ``-N``\ ``-Nx``\ RTS option RTS option to be used, - which allows threads to run in parallelparallelism on a - multiprocessormultiprocessorSMP or multicoremulticore machine. See - :ref:`using-smp`. +- It enables the :rts-flag:`-N` to be used, which allows threads to run in + parallelism on a multi-processor or multi-core machine. See :ref:`using-smp`. -- If a thread makes a foreign call (and the call is not marked - ``unsafe``), then other Haskell threads in the program will continue - to run while the foreign call is in progress. Additionally, - ``foreign export``\ ed Haskell functions may be called from multiple - OS threads simultaneously. See :ref:`ffi-threads`. +- If a thread makes a foreign call (and the call is not marked + ``unsafe``), then other Haskell threads in the program will continue + to run while the foreign call is in progress. Additionally, + ``foreign export``\ ed Haskell functions may be called from multiple + OS threads simultaneously. See :ref:`ffi-threads`. The following RTS option(s) affect the behaviour of Concurrent Haskell programs: @@ -33,16 +31,15 @@ programs: .. index:: single: RTS options; concurrent -``-Cs`` - .. index:: - single: -Cs; RTS option +.. rts-flag:: -C <s> + + :default: 20 milliseconds Sets the context switch interval to ⟨s⟩ seconds. A context switch will occur at the next heap block allocation after the timer expires (a heap block allocation occurs every 4k of allocation). With ``-C0`` or ``-C``, context switches will occur as - often as possible (at every heap block allocation). By default, - context switches occur every 20ms. + often as possible (at every heap block allocation). .. _using-smp: @@ -76,10 +73,11 @@ Compile-time options for SMP parallelism ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In order to make use of multiple CPUs, your program must be linked with -the ``-threaded`` option (see :ref:`options-linker`). Additionally, the +the :ghc-flag:`-threaded` option (see :ref:`options-linker`). Additionally, the following compiler options affect parallelism: -``-feager-blackholing`` +.. ghc-flag:: -feager-blackholing + Blackholing is the act of marking a thunk (lazy computuation) as being under evaluation. It is useful for three reasons: firstly it lets us detect certain kinds of infinite loop (the @@ -109,12 +107,8 @@ There are two ways to run a program on multiple processors: call ``Control.Concurrent.setNumCapabilities`` from your program, or use the RTS ``-N`` options. -``-N⟨x⟩`` -``-maxN⟨x⟩`` - - .. index:: - single: -N⟨x⟩; RTS option - single: -maxN(x); RTS option +.. rts-flag:: -N <x> + -maxN <x> Use ⟨x⟩ simultaneous threads when running the program. @@ -155,7 +149,8 @@ RTS ``-N`` options. The following options affect the way the runtime schedules threads on CPUs: -``-qa`` +.. rts-flag:: -qa + Use the OS's affinity facilities to try to pin OS threads to CPU cores. @@ -168,7 +163,8 @@ CPUs: this may or may not result in a performance improvement. We recommend trying it out and measuring the difference. -``-qm`` +.. rts-flag:: -qm + Disable automatic migration for load balancing. Normally the runtime will automatically try to schedule threads across the available CPUs to make use of idle CPUs; this option disables that behaviour. Note @@ -182,11 +178,11 @@ CPUs: Hints for using SMP parallelism ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Add the ``-s`` RTS option when running the program to see timing stats, +Add the :rts-flag:`-s` RTS option when running the program to see timing stats, which will help to tell you whether your program got faster by using more CPUs or not. If the user time is greater than the elapsed time, then the program used more than one CPU. You should also run the program -without ``-N`` for comparison. +without :rts-flag:`-N` for comparison. The output of ``+RTS -s`` tells you how many "sparks" were created and executed during the run of the program (see :ref:`rts-options-gc`), |