Commit 2dff2c7f authored by Ben Gamari's avatar Ben Gamari 🐢
Browse files

Fix more documentation wibbles

Fixes #14020, #14016, #14015, #14019
parent c9451959
......@@ -158,7 +158,7 @@ Compiler
(:ghc-ticket:`4012`)
- Nearly two-hundred more bugs. See `Trac
<https://ghc.haskell.org/trac/ghc/query?status=closed&milestone=8.0.2&col=id&col=summary&col=status&col=type&col=priority&col=milestone&col=component&order=priority>`_
<https://ghc.haskell.org/trac/ghc/query?status=closed&milestone=8.0.2&col=id&col=summary&col=status&col=type&col=priority&col=milestone&col=component&order=priority>`__
for a complete list.
Runtime system
......
......@@ -187,7 +187,7 @@ Compiler
-- uses of `Monoid MyMonoid` here are improved
bar :: MonadWriter MyMonoid m => ...
- GHC now derives the definition of ``<$`` when using :ghc-flag:`DeriveFunctor`
- GHC now derives the definition of ``<$`` when using :ghc-flag:`-XDeriveFunctor`
rather than using the default definition. This prevents unnecessary
allocation and a potential space leak when deriving ``Functor`` for
a recursive type.
......@@ -231,8 +231,8 @@ Compiler
instance Foo (Either a b) where
type Bar (Either a b) = b -> a
See the section on `associated type family instances <assoc-data-inst>` for
more information.
See the section on :ref:`associated type family instances <assoc-data-inst>`
for more information.
- A bug involving the interaction between :ghc-flag:`-XMonoLocalBinds` and
:ghc-flag:`-XPolyKinds` has been fixed. This can cause some programs to fail
......@@ -311,7 +311,7 @@ Runtime system
- Heap overflow throws a catchable exception, provided that it was detected
by the RTS during a GC cycle due to the program exceeding a limit set by
``+RTS -M`` (see :rts-flag:`-M`), and not due to an allocation being refused
``+RTS -M`` (see :rts-flag:`-M ⟨size⟩`), and not due to an allocation being refused
by the operating system. This exception is thrown to the same thread that
receives ``UserInterrupt`` exceptions, and may be caught by user programs.
......@@ -346,12 +346,13 @@ Runtime system
threads to all cores in systems which have multiple processor groups.
(e.g. > 64 cores, see :ghc-ticket:`11054`)
- Output of :ref:`Event log <rts-eventlog>` data can now be configured.
Enabling external tools to collect and analyze the event log data while the
- Output of :ref:`Event log <rts-eventlog>` data can now be configured,
enabling external tools to collect and analyze the event log data while the
application is still running.
- advapi32, shell32 and user32 are now automatically loaded in GHCi. libGCC is also
loaded when a depencency requires it. See :ghc-ticket:`13189`.
- ``advapi32``, ``shell32`` and ``user32`` are now automatically loaded in GHCi.
``libGCC`` is also loaded when a dependency requires it. See
:ghc-ticket:`13189`.
hsc2hs
~~~~~~
......
......@@ -12,7 +12,7 @@ import os
sys.path.insert(0, os.path.abspath('.'))
from ghc_config import extlinks, version
extensions = ['sphinx.ext.extlinks']
extensions = ['sphinx.ext.extlinks', 'sphinx.ext.mathjax']
templates_path = ['.templates']
source_suffix = '.rst'
......
......@@ -222,6 +222,8 @@ commands for referring to documentation for the following core GHC packages,
* ``cabal``: ``:cabal-ref:``
* ``ghc-prim``: ``:ghc-prim-ref:``
These are defined in :file:`docs/users_guide/ghc_config.py.in`.
For instance,
.. code-block:: rest
......@@ -229,6 +231,19 @@ For instance,
See the documentation for :base-ref:`Control.Applicative <Control-Applicative.html>`
for details.
Math
^^^^
You can insert type-set equations using ``:math:``. For instance,
.. code-block:: rest
Fick's law of diffusion, :math:`J = -D \frac{d \varphi}{d x}`, ...
will render as,
Fick's law of diffusion, :math:`J = -D \frac{d \varphi}{d x}`, ...
Index entries
~~~~~~~~~~~~~
......
......@@ -4,10 +4,13 @@ Foreign function interface (FFI)
================================
.. index::
single: -XForeignFunctionInterface
single: Foreign function interface
single: interfacing with native code
.. ghc-flag:: -XForeignFunctionInterface
Allow use of the Haskell foreign function interface.
GHC (mostly) conforms to the Haskell Foreign Function Interface, whose
definition is part of the Haskell Report on
`http://www.haskell.org/ <http://www.haskell.org/>`__.
......
extlinks = {
'base-ref': ('../libraries/base-@LIBRARY_base_VERSION@/%s', ''),
'cabal-ref': ('../libraries/Cabal-@LIBRARY_Cabal_VERSION@/%s', ''),
'compact-ref': ('../libraries/ghc-compact-@LIBRARY_compact_VERSION@/%s', ''),
'compact-ref': ('../libraries/ghc-compact-@LIBRARY_ghc_compact_VERSION@/%s', ''),
'ghc-prim-ref': ('../libraries/ghc-prim-@LIBRARY_ghc_prim_VERSION@/%s', ''),
'ghc-ticket': ('http://ghc.haskell.org/trac/ghc/ticket/%s', 'Trac #'),
'ghc-wiki': ('http://ghc.haskell.org/trac/ghc/wiki/%s', 'Trac #'),
'th-ref': ('../libraries/template-haskell-@LIBRARY_template_haskell_VERSION@/%s', ''),
'ghc-ticket': ('https://ghc.haskell.org/trac/ghc/ticket/%s', 'Trac #'),
'ghc-wiki': ('https://ghc.haskell.org/trac/ghc/wiki/%s', 'Trac #'),
}
version = '@ProjectVersion@'
......@@ -480,6 +480,11 @@ instead of layout:
6
Prelude>
.. ghci-cmd:: :{
:}
Begin or end a multi-line GHCi command block.
To alleviate this issue, GHCi commands can be split over multiple lines,
by wrapping them in ``:{`` and ``:}`` (each on a single line of its
own):
......
......@@ -4643,6 +4643,10 @@ Note the following details
Deriving strategies
-------------------
 
.. ghc-flag:: -XDerivingStrategies
Allow multiple ``deriving``, each optionally qualified with a *strategy*.
In most scenarios, every ``deriving`` statement generates a typeclass instance
in an unambiguous fashion. There is a corner case, however, where
simultaneously enabling both the :ghc-flag:`-XGeneralizedNewtypeDeriving` and
......@@ -4693,8 +4697,8 @@ Currently, the deriving strategies are:
 
If an explicit deriving strategy is not given, GHC has an algorithm for
determining how it will actually derive an instance. For brevity, the algorithm
is omitted here. You can read the full algorithm at
:ghc-wiki:`Wiki page <DerivingStrategies>`.
is omitted here. You can read the full algorithm on the
:ghc-wiki:`GHC Wiki <Commentary/Compiler/DerivingStrategies>`.
 
.. _pattern-synonyms:
 
......@@ -7119,6 +7123,7 @@ Decidability of type synonym instances
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
.. ghc-flag:: -XUndecidableInstances
:noindex:
 
Relax restrictions on the decidability of type synonym family instances.
 
......@@ -9969,7 +9974,7 @@ Here we do not need to give a type signature to ``w``, because it is an
argument of constructor ``T1`` and that tells GHC all it needs to know.
 
 
.. _implicit-quant:
.. _implicit-quantification:
 
Implicit quantification
-----------------------
......@@ -10126,14 +10131,15 @@ Here are some more details:
containing holes, by using the :ghc-flag:`-fdefer-typed-holes` flag. This
flag defers errors produced by typed holes until runtime, and
converts them into compile-time warnings. These warnings can in turn
be suppressed entirely by :ghc-flag:`-fno-warn-typed-holes`.
be suppressed entirely by :ghc-flag:`-Wno-typed-holes <-Wtyped-holes>`.
 
The same behaviour for "``Variable out of scope``" errors, it terminates
compilation by default. You can defer such errors by using the
:ghc-flag:`-fdefer-out-of-scope-variables` flag. This flag defers errors
produced by out of scope variables until runtime, and
converts them into compile-time warnings. These warnings can in turn
be suppressed entirely by :ghc-flag:`-fno-warn-deferred-out-of-scope-variables`.
be suppressed entirely by :ghc-flag:`-Wno-deferred-out-of-scope-variables
<-Wdeferred-out-of-scope-variables>`.
 
The result is that a hole or a variable will behave like ``undefined``, but with
the added benefits that it shows a warning at compile time, and will
......@@ -10662,17 +10668,18 @@ Enabling deferring of type errors
 
The flag :ghc-flag:`-fdefer-type-errors` controls whether type errors are
deferred to runtime. Type errors will still be emitted as warnings, but
will not prevent compilation. You can use
:ghc-flag:`-Wno-deferred-type-errors <-Wdeferred-type-errors>` to suppress these
warnings.
will not prevent compilation. You can use :ghc-flag:`-Wno-type-errors
<-Wtype-errors>` to suppress these warnings.
 
This flag implies the :ghc-flag:`-fdefer-typed-holes` and
:ghc-flag:`-fdefer-out-of-scope-variables` flags, which enables this
behaviour for `typed holes <#typed-holes>`__ and variables. Should you so wish, it is
:ghc-flag:`-fdefer-out-of-scope-variables` flags, which enables this behaviour
for `typed holes <#typed-holes>`__ and variables. Should you so wish, it is
possible to enable :ghc-flag:`-fdefer-type-errors` without enabling
:ghc-flag:`-fdefer-typed-holes` or :ghc-flag:`-fdefer-out-of-scope-variables`,
by explicitly specifying :ghc-flag:`-fno-defer-typed-holes` or :ghc-flag:`-fno-defer-out-of-scope-variables`
on the command-line after the :ghc-flag:`-fdefer-type-errors` flag.
by explicitly specifying :ghc-flag:`-fno-defer-typed-holes
<-fdefer-typed-holes>` or :ghc-flag:`-fno-defer-out-of-scope-variables
<-fdefer-out-of-scope-variables>` on the command-line after the
:ghc-flag:`-fdefer-type-errors` flag.
 
At runtime, whenever a term containing a type error would need to be
evaluated, the error is converted into a runtime exception of type
......@@ -10713,7 +10720,9 @@ Otherwise, in the common case of a simple type error such as typing
immediately-following type error when the expression is evaluated.
 
This exception doesn't apply to statements, as the following example
demonstrates: ::
demonstrates:
.. code-block:: none
 
Prelude> let x = (True, 1 == 'a')
 
......@@ -10737,12 +10746,10 @@ in "`Template Meta-programming for
Haskell <http://research.microsoft.com/~simonpj/papers/meta-haskell/>`__"
(Proc Haskell Workshop 2002).
 
There is a Wiki page about Template Haskell at
http://www.haskell.org/haskellwiki/Template_Haskell, and that is the
best place to look for further details. You may also consult the `online
Haskell library reference
material <http://www.haskell.org/ghc/docs/latest/html/libraries/index.html>`__
(look for module ``Language.Haskell.TH``). Many changes to the original
The `Template Haskell <http://www.haskell.org/haskellwiki/Template_Haskell>`__
page on the GHC Wiki has a wealth of information. You may also consult the
:th-ref:`Haddock reference documentation <Language-Haskell-TH.html>`.
Many changes to the original
design are described in `Notes on Template Haskell version
2 <http://research.microsoft.com/~simonpj/papers/meta-haskell/notes2.ps>`__.
Not all of these changes are in GHC, however.
......
......@@ -825,7 +825,7 @@ in ``list``, ``describe``, and ``field``, where a ``'*'`` indicates open
substring ends (``prefix*``, ``*suffix``, ``*infix*``). Examples (output
omitted):
::
.. code-block:: none
-- list all regex-related packages
ghc-pkg list '*regex*' --ignore-case
......
......@@ -80,10 +80,10 @@ Parallel Haskell
GHC includes support for running Haskell programs in parallel on
symmetric, shared-memory multi-processor (SMP). By default GHC runs
your program on one processor; if you want it to run in parallel you
must link your program with the ``-threaded``, and run it with the RTS
``-N`` option; see :ref:`using-smp`). The runtime will schedule the
running Haskell threads among the available OS threads, running as many
in parallel as you specified with the ``-N`` RTS option.
must link your program with the :ghc-flag:`-threaded`, and run it with the RTS
:rts-flag:`-N ⟨x⟩` option; see :ref:`using-smp`). The runtime will schedule the
running Haskell threads among the available OS threads, running as many in
parallel as you specified with the :rts-flag:`-N ⟨x⟩` RTS option.
Annotating pure code for parallelism
------------------------------------
......
......@@ -163,12 +163,15 @@ Options affecting the C pre-processor
.. ghc-flag:: -Dsymbol[=value]
Define macro symbol in the usual way. NB: does *not* affect ``-D``
macros passed to the C compiler when compiling with :ghc-flag:`-fvia-C`! For
those, use the ``-optc-Dfoo`` hack (see :ref:`forcing-options-through`).
Define macro symbol in the usual way. When no value is given, the value is
taken to be ``1``. For instance, ``-DUSE_MYLIB`` is equivalent to
``-DUSE_MYLIB=1``.
When no value is given, the value is taken to be ``1``. For instance,
``-DUSE_MYLIB`` is equivalent to ``-DUSE_MYLIB=1``.
.. note::
:ghc-flag:`-Dsymbol[=value]` does *not* affect ``-D``
macros passed to the C compiler when compiling an unregisterised build! In
this case use the ``-optc-Dfoo`` hack (see :ref:`forcing-options-through`).
.. ghc-flag:: -Usymbol
......
......@@ -571,7 +571,6 @@ For instance, a simple profile might look like this,
"src_loc": "<entire-module>",
"is_caf": true
}
...
],
"profile": {
"id": 162,
......@@ -1312,9 +1311,13 @@ case :file:`Recip.tix`, which contains the coverage data for this run of the
program. The program may be run multiple times (e.g. with different test
data), and the coverage data from the separate runs is accumulated in
the ``.tix`` file. To reset the coverage data and start again, just
remove the ``.tix`` file. You can control where the ``.tix`` file
remove the ``.tix`` file. You can control where the ``.tix`` file
is generated using the environment variable :envvar:`HPCTIXFILE`.
.. envvar:: HPCTIXFILE
Set the HPC ``.tix`` file output path.
Having run the program, we can generate a textual summary of coverage:
.. code-block:: none
......@@ -1566,6 +1569,10 @@ Using “ticky-ticky” profiling (for implementors)
.. index::
single: ticky-ticky profiling
.. ghc-flag:: -ticky
Enable ticky-ticky profiling.
Because ticky-ticky profiling requires a certain familiarity with GHC
internals, we have moved the documentation to the GHC developers wiki.
Take a look at its
......
......@@ -16,7 +16,7 @@ Usage
The ``runghc`` command-line looks like:
::
.. code-block:: none
runghc [runghc flags] [GHC flags] module [program args]
......
......@@ -84,7 +84,7 @@ As always, for RTS options that take ⟨size⟩s: If the last character of
or G, by 1,000,000,000. (And any wraparound in the counters is *your*
fault!)
Giving a ``+RTS -?`` ``-?``\ RTS option option will print out the RTS
Giving a ``+RTS -?`` RTS option option will print out the RTS
options actually available in your program (which vary, depending on how
you compiled).
......@@ -156,55 +156,51 @@ can override the defaults.
Owing to the vagaries of DLL linking, these hooks don't work under
Windows when the program is built dynamically.
Runtime events
##############
You can change the messages printed when the runtime system "blows up,"
e.g., on stack overflow. The hooks for these are as follows:
``void OutOfHeapHook (unsigned long, unsigned long)``
.. index::
single: OutOfHeapHook
.. c:function:: void OutOfHeapHook (unsigned long, unsigned long)
The heap-overflow message.
``void StackOverflowHook (long int)``
.. index::
single: StackOverflowHook
.. c:function:: void StackOverflowHook (long int)
The stack-overflow message.
``void MallocFailHook (long int)``
.. index::
single: MallocFailHook
.. c:function:: void MallocFailHook (long int)
The message printed if ``malloc`` fails.
Furthermore GHC lets you specify the way event log data (:rts-flag:`-l`)
is written through a custom `EventLogWriter`:
Event log output
################
``void initEventLogWriter(void)``
.. index::
single: initEventLogWriter
Furthermore GHC lets you specify the way event log data (see :rts-flag:`-l`) is
written through a custom :c:type:`EventLogWriter`:
Initializes your `EventLogWriter`. This is optional.
.. c:type:: EventLogWriter
``bool writeEventLog(void *eventlog, size_t eventlog_size)``
.. index::
single: writeEventLog
A sink of event-log data.
Hands buffered event log data to your event log writer.
Required for a custom `EventLogWriter`.
.. c:member:: void initEventLogWriter(void)
``void flushEventLog(void)``
.. index::
single: flushEventLog
Initializes your :c:type:`EventLogWriter`. This is optional.
Flush buffers (if any) of your custom `EventLogWriter`. This is
optional.
.. c:member:: bool writeEventLog(void *eventlog, size_t eventlog_size)
``void stopEventLogWriter(void)``
.. index::
single: stopEventLogWriter
Hands buffered event log data to your event log writer.
Required for a custom :c:type:`EventLogWriter`.
.. c:member:: void flushEventLog(void)
Flush buffers (if any) of your custom :c:type:`EventLogWriter`. This can
be ``NULL``.
.. c:member:: void stopEventLogWriter(void)
Called when event logging is about to stop. This is optional.
Called when event logging is about to stop. This can be ``NULL``.
.. _rts-options-misc:
......@@ -214,7 +210,7 @@ Miscellaneous RTS options
.. rts-flag:: --install-signal-handlers=⟨yes|no⟩
If yes (the default), the RTS installs signal handlers to catch
things like ctrl-C. This option is primarily useful for when you are
things like :kbd:`Ctrl-C`. This option is primarily useful for when you are
using the Haskell code as a DLL, and want to set your own signal
handlers.
......@@ -294,7 +290,7 @@ performance.
.. rts-flag:: -AL ⟨size⟩
:default: ``-A`` value
:default: :rts-flag:`-A <-A ⟨size⟩>` value
:since: 8.2.1
.. index::
......@@ -302,7 +298,8 @@ performance.
Sets the limit on the total size of "large objects" (objects
larger than about 3KB) that can be allocated before a GC is
triggered. By default this limit is the same as the ``-A`` value.
triggered. By default this limit is the same as the :rts-flag:`-A <-A
⟨size⟩>` value.
Large objects are not allocated from the normal allocation area
set by the ``-A`` flag, which is why there is a separate limit for
......@@ -334,7 +331,7 @@ performance.
.. rts-flag:: -n ⟨size⟩
:default: 4m with ``-A16m`` or larger, otherwise 0.
:default: 4m with :rts-flag:`-A16m <-A ⟨size⟩>` or larger, otherwise 0.
.. index::
single: allocation area, chunk size
......@@ -383,14 +380,13 @@ performance.
requested using the ``-G1`` option.
.. rts-flag:: -c ⟨n⟩
:noindex:
:default: 30
Automatically enable compacting collection when the live data exceeds ⟨n⟩%
of the maximum heap size (see the :rts-flag:`-M ⟨size⟩` option). Note that
the maximum heap size is unlimited by default, so this option has no effect
unless the maximum heap size is set with ``-M ⟨size⟩.``
unless the maximum heap size is set with :rts-flag:`-M ⟨size⟩`.
.. rts-flag:: -F ⟨factor⟩
......@@ -408,11 +404,10 @@ performance.
The default seems to work well here. If you have plenty of memory, it is
usually better to use ``-H ⟨size⟩`` (see :rts-flag:`-H [⟨size⟩]`) than to
increase ``-F ⟨factor⟩.``
increase :rts-flag:`-F ⟨factor⟩`.
The ``-F ⟨factor⟩`` setting will be automatically reduced by the garbage
collector when the maximum heap size (the ``-M ⟨size⟩`` setting, see
:rts-flag:`-M ⟨size⟩`) is approaching.
The :rts-flag:`-F ⟨factor⟩` setting will be automatically reduced by the garbage
collector when the maximum heap size (the :rts-flag:`-M ⟨size⟩` setting) is approaching.
.. rts-flag:: -G ⟨generations⟩
......@@ -444,17 +439,17 @@ performance.
parallel GC completely, reverting to sequential GC.
The default parallel GC settings are usually suitable for parallel programs
(i.e. those using ``par``, Strategies, or with multiple threads). However,
it is sometimes beneficial to enable the parallel GC for a single-threaded
sequential program too, especially if the program has a large amount of
heap data and GC is a significant fraction of runtime. To use the parallel
GC in a sequential program, enable the parallel runtime with a suitable
:rts-flag:`-N ⟨x⟩` option, and additionally it might be beneficial to
restrict parallel GC to the old generation with ``-qg1``.
(i.e. those using :base-ref:`par <GHC-Conc.html#v:par>`, Strategies, or with
multiple threads). However, it is sometimes beneficial to enable the
parallel GC for a single-threaded sequential program too, especially if the
program has a large amount of heap data and GC is a significant fraction of
runtime. To use the parallel GC in a sequential program, enable the parallel
runtime with a suitable :rts-flag:`-N ⟨x⟩` option, and additionally it might
be beneficial to restrict parallel GC to the old generation with ``-qg1``.
.. rts-flag:: -qb ⟨gen⟩
:default: 1 for ``-A`` < 32M, 0 otherwise
:default: 1 for :rts-flag:`-A <-A ⟨size⟩>` < 32M, 0 otherwise
:since: 6.12.1
Use load-balancing in the parallel GC in generation ⟨gen⟩ and higher.
......@@ -472,7 +467,7 @@ performance.
.. rts-flag:: -qn ⟨x⟩
:default: the value of ``-N`` or the number of CPU cores,
:default: the value of :rts-flag:`-N <-N ⟨x⟩>` or the number of CPU cores,
whichever is smaller.
:since: 8.2.1
......@@ -758,7 +753,7 @@ RTS options to produce runtime statistics
data during a major GC, which is why the number of samples
corresponds to the number of major GCs (and is usually relatively
small). To get a better picture of the heap profile of your
program, use the ``-hT`` RTS option (:ref:`rts-profiling`).
program, use the :rts-flag:`-hT` RTS option (:ref:`rts-profiling`).
- The peak memory the RTS has allocated from the OS.
......@@ -917,13 +912,14 @@ one profiling option that is available for ordinary non-profiled
executables:
.. rts-flag:: -hT
-h
Generates a basic heap profile, in the file :file:`prog.hp`. To produce the
heap profile graph, use :command:`hp2ps` (see :ref:`hp2ps`). The basic heap
profile is broken down by data constructor, with other types of closures
(functions, thunks, etc.) grouped into broad categories (e.g. ``FUN``,
``THUNK``). To get a more detailed profile, use the full profiling support
(:ref:`profiling`). Can be shortened to ``-h``.
(:ref:`profiling`). Can be shortened to :rts-flag:`-h`.
.. rts-flag:: -L ⟨n⟩
......
......@@ -375,7 +375,7 @@ Safe Imports
Safe Haskell enables a small extension to the usual import syntax of
Haskell, adding a ``safe`` keyword:
::
.. code-block:: none
impdecl -> import [safe] [qualified] modid [as modid] [impspec]
......
......@@ -312,7 +312,7 @@ Use a bigger heap!
to let GHC calculate a value based on the amount of live data.
Compact your data:
The :compact-ref:`GHC.Compact <GHC-Compact.html>` module
The :ghc-compact-ref:`GHC.Compact <GHC-Compact.html>` module
provides a way to make garbage collection more efficient for
long-lived data structures. Compacting a data structure collects
the objects together in memory, where they are treated as a single
......
......@@ -86,7 +86,7 @@ following compiler options affect parallelism:
parallel program, because we can tell when a computation is already
in progress.
The option ``-feager-blackholing`` causes each thunk to be
The option :ghc-flag:`-feager-blackholing` causes each thunk to be
blackholed as soon as evaluation begins. The default is "lazy
blackholing", whereby thunks are only marked as being under
evaluation when a thread is paused for some reason. Lazy blackholing
......@@ -96,7 +96,7 @@ following compiler options affect parallelism:
turns out to be important for parallelism.
We recommend compiling any code that is intended to be run in
parallel with the ``-feager-blackholing`` flag.
parallel with the :ghc-flag:`-feager-blackholing` flag.
.. _parallel-options:
......@@ -104,8 +104,9 @@ RTS options for SMP parallelism
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are two ways to run a program on multiple processors: call
``Control.Concurrent.setNumCapabilities`` from your program, or use the
RTS ``-N`` options.
:base-ref:`Control.Concurrent.setNumCapabilities
<Control.Concurrent.html#v:setNumCapabilities>` from your program, or
use the RTS :rts-flag:`-N ⟨x⟩` options.
.. rts-flag:: -N ⟨x⟩
-maxN ⟨x⟩
......@@ -155,10 +156,9 @@ CPUs:
Use the OS's affinity facilities to try to pin OS threads to CPU
cores.
When this option is enabled, the OS threads for a capability *i* are
bound to the CPU core *i* using the API provided by the OS for
setting thread affinity. e.g. on Linux GHC uses
``sched_setaffinity()``.
When this option is enabled, the OS threads for a capability :math:`i` are
bound to the CPU core :math:`i` using the API provided by the OS for setting
thread affinity. e.g. on Linux GHC uses ``sched_setaffinity()``.
Depending on your workload and the other activity on the machine,
this may or may not result in a performance improvement. We
......@@ -174,7 +174,7 @@ CPUs:
This option is probably only of use for concurrent programs that
explicitly schedule threads onto CPUs with
``Control.Concurrent.forkOn``.
:base-ref:`Control.Concurrent.forkOn <Control-Concurrent.html#v:forkOn>`.
Hints for using SMP parallelism
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
......
......@@ -186,7 +186,7 @@ of ``-W(no-)*``.
.. ghc-flag:: -fdefer-out-of-scope-variables
Defer variable out of scope errors (errors about names without a leading underscore)
Defer variable out-of-scope errors (errors about names without a leading underscore)
until runtime. This will turn variable-out-of-scope errors into warnings.
Using a value that depends on a typed hole produces a runtime error,