%************************************************************************
The basic task of the @ghc@ driver is to run each input file
-through the right phases (parsing, linking, etc.).
+through the right phases (compiling, linking, etc.).
The first phase to run is determined by the input-file suffix, and the
last phase is determined by a flag. If no relevant flag is present,
<nidx>standard error, saving</nidx>
Sometimes, you may cause GHC to be rather chatty on standard error;
-with @-fshow-import-specs@, for example. You can instruct GHC to
-<em>append</em> this output to a particular log file with a @-odump
-<blah>@<nidx>-odump <blah> option</nidx> option.
+with @-v@, for example. You can instruct GHC to <em>append</em> this
+output to a particular log file with a @-odump <blah>@<nidx>-odump
+<blah> option</nidx> option.
<sect2> Redirecting temporary files
<label id="temp-files">
<tag>@-W@:</tag>
<nidx>-W option</nidx>
-Provides the standard warnings plus @-fwarn-incomplete-patterns@
-and @-fwarn-unused-names@.
+Provides the standard warnings plus @-fwarn-incomplete-patterns@,
+@-fwarn-unused-imports@ and @-fwarn-unused-binds@.
<tag>@-Wall@:</tag>
<nidx>-Wall option</nidx>
<nidx>overlapping patterns, warning</nidx>
<nidx>patterns, overlapping</nidx>
-By default, the compiler will warn you if a set of patterns are either
-incomplete (i.e., you're only matching on a subset of an algebraic
-data type's constructors), or overlapping, i.e.,
+By default, the compiler will warn you if a set of patterns are
+overlapping, i.e.,
<tscreen><verb>
f :: String -> Int
f [] = 0
f (_:xs) = 1
f "2" = 2
-
-g [] = 2
</verb></tscreen>
where the last pattern match in @f@ won't ever be reached, as the
<nidx>incomplete patterns, warning</nidx>
<nidx>patterns, incomplete</nidx>
-Similarly for incomplete patterns, the function @g@ will fail when
-applied to non-empty lists, so the compiler will emit a warning about
-this when this option is enabled.
+Similarly for incomplete patterns, the function @g@ below will fail
+when applied to non-empty lists, so the compiler will emit a warning
+about this when @-fwarn-incomplete-patterns@ is enabled.
+
+<tscreen><verb>
+g [] = 2
+</verb></tscreen>
+
+This option isn't enabled be default because it can be a bit noisy,
+and it doesn't always indicate a bug in the program. However, it's
+generally considered good practice to cover all the cases in your
+functions.
<tag>@-fwarn-missing-methods@:</tag>
<nidx>-fwarn-missing-methods option</nidx>
declaration is missing one or more methods, and the corresponding
class declaration has no default declaration for them.
-<tag>@-fwarn-unused-names@:</tag>
-<nidx>-fwarn-unused-names option</nidx>
-<nidx>unused names, warning</nidx>
-<nidx>names, unused</nidx>
+<tag>@-fwarn-unused-imports@:</tag>
+<nidx>-fwarn-unused-imports option</nidx>
+<nidx>unused imports, warning</nidx>
+<nidx>imports, unused</nidx>
-Have the renamer report which locally defined names are not used/exported.
+Report any objects that are explicitly imported but never used.
+
+<tag>@-fwarn-unused-binds@:</tag>
+<nidx>-fwarn-unused-binds option</nidx>
+<nidx>unused binds, warning</nidx>
+<nidx>binds, unused</nidx>
+
+Report any function definitions (and local bindings) which are unused.
+For top-level functions, the warning is only given if the binding is
+not exported.
+
+<tag>@-fwarn-unused-matches@:</tag>
+<nidx>-fwarn-unused-matches option</nidx>
+<nidx>unused matches, warning</nidx>
+<nidx>matches, unused</nidx>
+
+Report all unused variables which arise from pattern matches,
+including patterns consisting of a single variable. For instance @f x
+y = []@ would report @x@ and @y@ as unused. To eliminate the warning,
+all unused variables can be replaced with wildcards.
<tag>@-fwarn-duplicate-exports@:</tag>
<nidx>-fwarn-duplicate-exports option</nidx>
This option is on by default.
-</descrip>
+<tag><tt>-fwarn-type-defaults</tt>:</tag>
+<nidx>-fwarn-type-defaults option</nidx>
+<nidx>defaulting mechanism, warning</nidx>
+
+Have the compiler warn/inform you where in your source the Haskell
+defaulting mechanism for numeric types kicks in. This is useful
+information when converting code from a context that assumed one
+default into one with another, e.g., the 'default default' for Haskell
+1.4 caused the otherwise unconstrained value <tt>1</tt> to be given
+the type <tt>Int</tt>, whereas Haskell 98 defaults it to
+<tt>Integer</tt>. This may lead to differences in performance and
+behaviour, hence the usefulness of being non-silent about this.
+
+This warning is off by default.
-If you would like GHC to check that every top-level value has a type
-signature, use the @-fsignatures-required@
-option.<nidx>-fsignatures-required option</nidx>
+<tag>@-fwarn-missing-signatures@:</tag>
+<nidx>-fwarn-missing-signatures option</nidx>
+<nidx>type signatures, missing</nidx>
+
+If you would like GHC to check that every top-level function/value has
+a type signature, use the @-fwarn-missing-signatures@ option. This
+option is off by default.
+
+</descrip>
If you're feeling really paranoid, the @-dcore-lint@
option<nidx>-dcore-lint option</nidx> is a good choice. It turns on
When GHC compiles a source file @F@ which contains a module @A@, say,
it generates an object @F.o@, <em>and</em> a companion <em>interface
-file</em> @A.hi@.
+file</em> @A.hi@. The interface file is not intended for human
+consumption, as you'll see if you take a look at one. It's merely
+there to help the compiler compile other modules in the same program.
NOTE: Having the name of the interface file follow the module name and
not the file name, means that working with tools such as @make(1)@
It has a builtin list of directories (notably including @.@) where
it looks.
-The @-i<dirs>@ option<nidx>-i<dirs> option</nidx> prepends a
-colon-separated list of @dirs@ to the ``import directories'' list.
+<descrip>
-A plain @-i@ resets the ``import directories'' list back to nothing.
+<tag>@-i<dirs>@</tag><nidx>-i<dirs> option</nidx> This flag
+prepends a colon-separated list of @dirs@ to the ``import
+directories'' list.
-GHC normally imports @Prelude.hi@ files for you. If you'd rather
-it didn't, then give it a @-fno-implicit-prelude@
-option<nidx>-fno-implicit-prelude option</nidx>. You are unlikely to get
-very far without a Prelude, but, hey, it's a free country.
+<tag>@-i@</tag> resets the ``import directories'' list back to nothing.
-If you are using a system-supplied non-Prelude library (e.g., the HBC
-library), just use a @-syslib hbc@<nidx>-syslib <lib> option</nidx>
-option (for example). The right interface files should then be
-available.
+<tag>@-fno-implicit-prelude@</tag>
+<nidx>-fno-implicit-prelude option</nidx>
+GHC normally imports @Prelude.hi@ files for you. If you'd rather it
+didn't, then give it a @-fno-implicit-prelude@ option. You are
+unlikely to get very far without a Prelude, but, hey, it's a free
+country.
+
+<tag>@-syslib <lib>@</tag>
+<nidx>-syslib <lib> option</nidx>
+
+If you are using a system-supplied non-Prelude library (e.g., the
+POSIX library), just use a @-syslib posix@ option (for example). The
+right interface files should then be available. Section <ref
+name="The GHC Prelude and Libraries" id="ghc-prelude"> lists the
+libraries available by this mechanism.
+
+<tag>@-I<dir>@</tag>
+<nidx>-I<dir> option</nidx>
Once a Haskell module has been compiled to C (@.hc@ file), you may
-wish to specify where GHC tells the C compiler to look for @.h@
-files. (Or, if you are using the @-cpp@ option<nidx>-cpp option</nidx>,
-where it tells the C pre-processor to look...) For this purpose, use
-a @-I<dir>@<nidx>-I<dir> option</nidx> in the usual C-ish way.
+wish to specify where GHC tells the C compiler to look for @.h@ files.
+(Or, if you are using the @-cpp@ option<nidx>-cpp option</nidx>, where
+it tells the C pre-processor to look...) For this purpose, use a @-I@
+option in the usual C-ish way.
+
+</descrip>
%************************************************************************
%* *
<nidx>-fno-prune-tydecls option</nidx><nidx>-fno-prune-instdecls
option</nidx>
-See also Section <ref name="Linking and consistency-checking" id="options-linker">, which describes how the linker
-finds standard Haskell libraries.
+See also Section <ref name="Linking and consistency-checking"
+id="options-linker">, which describes how the linker finds standard
+Haskell libraries.
%************************************************************************
%* *
%************************************************************************
%* *
+<sect2>How to compile mutually recursive modules
+<label id="mutual-recursion">
+<p>
+<nidx>module system, recursion</nidx>
+<nidx>recursion, between modules</nidx>
+%* *
+%************************************************************************
+
+Currently, the compiler does not have proper support for dealing with
+mutually recursive modules:
+
+<tscreen><verb>
+module A where
+
+import B
+
+newtype A = A Int
+
+f :: B -> A
+f (B x) = A x
+--------
+module B where
+
+import A
+
+data B = B !Int
+
+g :: A -> B
+g (A x) = B x
+</verb></tscreen>
+
+When compiling either module A and B, the compiler will try (in vain)
+to look for the interface file of the other. So, to get mutually
+recursive modules off the ground, you need to hand write an interface
+file for A or B, so as to break the loop. These hand-written
+interface files are called @hi-boot@ files, and are placed in a file
+called @<module>.hi-boot@. To import from an @hi-boot@ file instead
+of the standard @.hi@ file, use the following syntax in the importing module:
+<nidx>hi-boot files</nidx>
+<nidx>importing, hi-boot files</nidx>
+
+<tscreen> <verb>
+import {-# SOURCE #-} A
+</verb> </tscreen>
+
+The hand-written interface need only contain the bare minimum of
+information needed to get the bootstrapping process started. For
+example, it doesn't need to contain declarations for <em/everything/
+that module @A@ exports, only the things required by the module that
+imports @A@ recursively.
+
+For the example at hand, the boot interface file for A would look like
+the following:
+
+<tscreen><verb>
+__interface A 1 where
+__exports A A f;
+__import PrelBase Int;
+1 newtype A = A PrelBase.Int ;
+1 f :: A -> A ;
+</verb></tscreen>
+
+The syntax is essentially the same as a normal @.hi@ file
+(unfortunately), but you can usually tailor an existing @.hi@ file to
+make a @.hi-boot@ file.
+
+Notice that we only put the declaration for the newtype @A@ in the
+@hi-boot@ file, not the signature for @f@, since @f@ isn't used by
+@B@.
+
+The number ``1'' at the beginning of a declaration is the <em>version
+number</em> of that declaration: for the purposes of @.hi-boot@ files
+these can all be set to 1. All names must be fully qualified with the
+<em/original/ module that an object comes from: for example, the
+reference to @Int@ in the interface for @A@ comes from @PrelBase@,
+which is a module internal to GHC's prelude. It's a pain, but that's
+the way it is.
+
+<bf>Note:</bf> This is all a temporary solution, a version of the
+compiler that handles mutually recursive properly without the manual
+construction of interface files, is in the works.
+
+%************************************************************************
+%* *
<sect1>Optimisation (code improvement)
<label id="options-optimise">
<p>
<nidx>-Onot option</nidx>
<nidx>optimising, reset</nidx>
-This option will make GHC ``forget'' any -Oish options it has seen so
+This option will make GHC ``forget'' any @-O@ish options it has seen so
far. Sometimes useful; for example: @make all EXTRA_HC_OPTS=-Onot@.
<tag>@-Ofile <file>@:</tag>
something. When we want to go for broke, we tend to use @-O -fvia-C
-O2-for-C@ (and we go for lots of coffee breaks).
-The easiest way to see what @-O@ (etc) ``really mean'' is to run with
+The easiest way to see what @-O@ (etc.) ``really mean'' is to run with
@-v@, then stand back in amazement. Alternatively, just look at the
@HsC_minus<blah>@ lists in the @ghc@ driver script.
@-fno-specialise@<nidx>-fno-specialise option</nidx> (automatic
specialisation of overloaded functions [because it makes your code
bigger]) [US spelling also accepted], and
-@-fno-update-analyser@<nidx>-fno-update-analyser option</nidx>
-(update analyser, because it sometimes takes a <em>long</em> time).
+@-fno-update-analysis@<nidx>-fno-update-analysis option</nidx> (update
+analyser, because it sometimes takes a <em>long</em> time). This one
+is only enabled with -O2 anyway.
Should you wish to turn individual flags <em>on</em>, you are advised
to use the @-Ofile@ option, described above. Because the order in
The lower-case incantation, @-fvia-c@, is synonymous.
-<tag>@-funfolding-creation-threshold<n>@:</tag>
-<nidx>-funfolding-creation-threshold option</nidx>
+Compiling via C will probably be slower (in compilation time) than
+using GHC's native code generator.
+
+<tag>@-funfolding-interface-threshold<n>@:</tag>
+<nidx>-funfolding-interface-threshold option</nidx>
<nidx>inlining, controlling</nidx>
<nidx>unfolding, controlling</nidx>
(Default: 30) By raising or lowering this number, you can raise or
lower the amount of pragmatic junk that gets spewed into interface
files. (An unfolding has a ``size'' that reflects the cost in terms
of ``code bloat'' of expanding that unfolding in another module. A
-bigger Core expression would be assigned a bigger cost.)
+bigger function would be assigned a bigger cost.)
+
+<tag>@-funfolding-creation-threshold<n>@:</tag>
+<nidx>-funfolding-creation-threshold option</nidx>
+<nidx>inlining, controlling</nidx>
+<nidx>unfolding, controlling</nidx>
+(Default: 30) This option is similar to
+@-funfolding-interface-threshold@, except that it governs unfoldings
+within a single module. Increasing this figure is more likely to
+result in longer compile times than faster code. The next option is
+more useful:
<tag>@-funfolding-use-threshold<n>@:</tag>
<nidx>-funfolding-use-threshold option</nidx>
<nidx>inlining, controlling</nidx>
<nidx>unfolding, controlling</nidx>
-(Default: 3) By raising or lowering this number, you can make the
-compiler more or less keen to expand unfoldings.
-
-OK, folks, these magic numbers `30' and `3' are mildly arbitrary; they
-are of the ``seem to be OK'' variety. The `3' is the more critical
-one; it's what determines how eager GHC is about expanding unfoldings.
-
-% <tag>@-funfolding-override-threshold<n>@:</tag>
-% (Default: 8) [Pretty obscure]
-W hen deciding what unfoldings from a module should be made available
-% to the rest of the world (via this module's interface), the compiler
-% normally likes ``small'' expressions.
-
-% For example, if it sees @foo = bar@, it will decide that the very
-% small expression @bar@ is a great unfolding for @foo@. But if
-% @bar@ turns out to be @(True,False,True)@, we would probably
-% prefer <em>that</em> for the unfolding for @foo@.
-
-% Should we ``override'' the initial small unfolding from @foo=bar@
-% with the bigger-but-better one? Yes, if the bigger one's ``size'' is
-% still under the ``override threshold.'' You can use this flag to
-% adjust this threshold (why, I'm not sure).
-
-% <tag>@-fliberated-case-threshold<n>@:</tag>
-% (Default: 12) [Vastly obscure: NOT IMPLEMENTED YET]
-% ``Case liberation'' lifts evaluation out of recursive functions; it
-% does this by duplicating code. Done without constraint, you can get
-% serious code bloat; so we only do it if the ``size'' of the duplicated
-% code is smaller than some ``threshold.'' This flag can fiddle that
-% threshold.
+(Default: 8) This is the magic cut-off figure for unfolding: below
+this size, a function definition will be unfolded at the call-site,
+any bigger and it won't. The size computed for a function depends on
+two things: the actual size of the expression minus any discounts that
+apply (see @-funfolding-con-discount@).
+
+<tag>@-funfolding-con-discount<n>@:</tag>
+<nidx>-funfolding-con-discount option</nidx>
+<nidx>inlining, controlling</nidx>
+<nidx>unfolding, controlling</nidx>
+(Default: 2) If the compiler decides that it can eliminate some
+computation by performing an unfolding, then this is a discount factor
+that it applies to the funciton size before deciding whether to unfold
+it or not.
+
+OK, folks, these magic numbers `30', `8', and '2' are mildly
+arbitrary; they are of the ``seem to be OK'' variety. The `8' is the
+more critical one; it's what determines how eager GHC is about
+expanding unfoldings.
+
+<tag>@-funbox-strict-fields@:</tag>
+<nidx>-funbox-strict-fields option</nidx>
+<nidx>strict constructor fields</nidx>
+<nidx>constructor fields, strict</nidx>
+
+This option causes all constructor fields which are marked strict
+(i.e. ``!'') to be unboxed or unpacked if possible. For example:
+
+<tscreen><verb>
+data T = T !Float !Float
+</verb></tscreen>
+
+will create a constructor @T@ containing two unboxed floats if the
+@-funbox-strict-fields@ flag is given. This may not always be an
+optimisation: if the @T@ constructor is scrutinised and the floats
+passed to a non-strict function for example, they will have to be
+reboxed (this is done automatically by the compiler).
+
+This option should only be used in conjunction with @-O@, in order to
+expose unfoldings to the compiler so the reboxing can be removed as
+often as possible. For example:
+
+<tscreen><verb>
+f :: T -> Float
+f (T f1 f2) = f1 + f2
+</verb></tscreen>
+
+The compiler will avoid reboxing @f1@ and @f2@ by inlining @+@ on
+floats, but only when @-O@ is on.
+
+Any single-constructor data is eligible for unpacking; for example
+
+<tscreen><verb>
+data T = T !(Int,Int)
+</verb></tscreen>
+
+will store the two @Int@s directly in the @T@ constructor, by flattening
+the pair. Multi-level unpacking is also supported:
+
+<tscreen><verb>
+data T = T !S
+data S = S !Int !Int
+</verb></tscreen>
+
+will store two unboxed @Int#@s directly in the @T@ constructor.
<tag>@-fsemi-tagging@:</tag>
This option (which <em>does not work</em> with the native-code generator)
<tag>@-D<foo>@:</tag>
<nidx>-D<name> option</nidx>
Define macro @<foo>@ in the usual way. NB: does <em>not</em> affect
-@-D@ macros passed to the C~compiler when compiling via C! For
-those, use the @-optc-Dfoo@ hack...
+@-D@ macros passed to the C~compiler when compiling via C! For those,
+use the @-optc-Dfoo@ hack... (see Section <ref name="Forcing options
+to a particular phase." id="forcing-options-through">).
<tag>@-U<foo>@:</tag>
<nidx>-U<name> option</nidx>
The @ghc@ driver pre-defines several macros:
<descrip>
+<tag>@__HASKELL98__@:</tag>
+<nidx>__HASKELL98__</nidx>
+If defined, this means that GHC supports the language
+defined by the Haskell 98 report.
+
+NB. This macro is <em/only/ set when pre-processing Haskell source
+(ie. @.hs@ or @.lhs@ files).
+
<tag>@__HASKELL1__@:</tag>
<nidx>__HASKELL1__ macro</nidx>
-If defined to $n$, that means GHC supports the
-Haskell language defined in the Haskell report version $1.n$.
-Currently 4.
+If defined to <em/n/, that means GHC supports the
+Haskell language defined in the Haskell report version <em/1.n/.
+Currently 5.
-NB: This macro is set both when pre-processing Haskell source and
-when pre-processing generated C (@.hc@) files.
+NB. As with <tt/__HASKELL98__/, this macro is <em/only/ set when
+pre-processing Haskell source (ie. @.hs@ or @.lhs@ files).
<tag>@__GLASGOW_HASKELL__@:</tag>
<nidx>__GLASGOW_HASKELL__ macro</nidx>
-For version $n$ of the GHC system, this will be @#define@d to
-$100 \times n$. So, for version~3.00, it is 300.
-
-This macro is <em>only</em> set when pre-processing Haskell source.
-(<em>Not</em> when pre-processing generated C.)
+For version <em/n/ of the GHC system, this will be @#define@d to
+<em/100n/. So, for version 4.00, it is 400.
With any luck, @__GLASGOW_HASKELL__@ will be undefined in all other
implementations that support C-style pre-processing.
(For reference: the comparable symbols for other systems are:
@__HUGS__@ for Hugs and @__HBC__@ for Chalmers.)
+NB. This macro is set when pre-processing both Haskell source and C
+source, including the C source generated from a Haskell module
+(ie. @.hs@, @.lhs@, @.c@ and @.hc@ files).
+
<tag>@__CONCURRENT_HASKELL__@:</tag>
<nidx>__CONCURRENT_HASKELL__ macro</nidx>
-Only defined when @-concurrent@ is in use!
This symbol is defined when pre-processing Haskell (input) and
-pre-processing C (GHC output).
+pre-processing C (GHC output). Since GHC from verion 4.00 now
+supports concurrent haskell by default, this symbol is always defined.
<tag>@__PARALLEL_HASKELL__@:</tag>
<nidx>__PARALLEL_HASKELL__ macro</nidx>
Section <ref name="Forcing options to a particular phase." id="forcing-options-through">).
A small word of warning: @-cpp@ is not friendly to ``string
-gaps''.<nidx>-cpp vs string gaps</nidx><nidx>string gaps vs -cpp</nidx>. In
-other words, strings such as the following:
+gaps''.<nidx>-cpp vs string gaps</nidx><nidx>string gaps vs
+-cpp</nidx>. In other words, strings such as the following:
<tscreen><verb>
strmod = "\
for a parallel machine and the others weren't.) You may turn off this
check with @-no-link-chk@. You can turn it (back) on with
@-link-chk@ (the default).
+
+<tag><tt>-no-hs-main</tt>:</tag>
+<nidx>-no-hs-main option</nidx>
+<nidx>linking Haskell libraries with foreign code</nidx>
+
+In the event you want to include ghc-compiled code as part of another
+(non-Haskell) program, the RTS will not be supplying its definition of
+<tt/main()/ at link-time, you will have to. To signal that to the
+driver script when linking, use <tt/-no-hs-main/.
+
+Notice that since the command-line passed to the linker is rather
+involved, you probably want to use the ghc driver script to do the
+final link of your `mixed-language' application. This is not a
+requirement though, just try linking once with <tt/-v/ on to see what
+options the driver passes through to the linker.
+
</descrip>
%************************************************************************
%* *
%************************************************************************
-To compile a program as Concurrent Haskell, use the @-concurrent@
-option,<nidx>-concurrent option</nidx> both when compiling <em>and
-linking</em>. You will probably need the @-fglasgow-exts@ option, too.
+GHC (as of version 4.00) supports Concurrent Haskell by default,
+without requiring a special option or libraries compiled in a certain
+way. To get access to the support libraries for Concurrent Haskell
+(ie. @Concurrent@ and friends), use the @-syslib concurrent@ option.
Three RTS options are provided for modifying the behaviour of the
threaded runtime system. See the descriptions of @-C[<us>]@, @-q@,
-and @-t<num>@ in Section <ref name="RTS options for Concurrent/Parallel Haskell" id="parallel-rts-opts">.
-
-%************************************************************************
-%* *
-<sect2>Potential problems with Concurrent Haskell
-<label id="concurrent-problems">
-<p>
-<nidx>Concurrent Haskell problems</nidx>
-<nidx>problems, Concurrent Haskell</nidx>
-%* *
-%************************************************************************
-
-The main thread in a Concurrent Haskell program is given its own
-private stack space, but all other threads are given stack space from
-the heap. Stack space for the main thread can be
-adjusted as usual with the @-K@ RTS
-option,<nidx>-K RTS option (concurrent, parallel)</nidx> but if this
-private stack space is exhausted, the main thread will switch to stack
-segments in the heap, just like any other thread. Thus, problems
-which would normally result in stack overflow in ``sequential Haskell''
-can be expected to result in heap overflow when using threads.
-
-The concurrent runtime system uses black holes as synchronisation
-points for subexpressions which are shared among multiple threads. In
-``sequential Haskell'', a black hole indicates a cyclic data
-dependency, which is a fatal error. However, in concurrent execution, a
-black hole may simply indicate that the desired expression is being
-evaluated by another thread. Therefore, when a thread encounters a
-black hole, it simply blocks and waits for the black hole to be
-updated. Cyclic data dependencies will result in deadlock, and the
-program will fail to terminate.
-
-Because the concurrent runtime system uses black holes as
-synchronisation points, it is not possible to disable black-holing
-with the @-N@ RTS option.<nidx>-N RTS option</nidx> Therefore, the use
-of signal handlers (including timeouts) with the concurrent runtime
-system can lead to problems if a thread attempts to enter a black hole
-that was created by an abandoned computation. The use of signal
-handlers in conjunction with threads is strongly discouraged.
+and @-t<num>@ in Section <ref name="RTS options for
+Concurrent/Parallel Haskell" id="parallel-rts-opts">.
+Concurrent Haskell is described in more detail in Section <ref
+name="Concurrent and Parallel Haskell" id="concurrent-and-parallel">.
%************************************************************************
%* *
the finest granularity possible, short of a context switch at every
heap allocation.
+[NOTE: this option currently has no effect (version 4.00). Context
+switches happen when the current heap block is full, i.e. every 4k of
+allocation].
+
<tag>@-q[v]@:</tag>
<nidx>-q RTS option</nidx>
-Produce a quasi-parallel profile of thread activity, in the file
-@<program>.qp@. In the style of @hbcpp@, this profile records
-the movement of threads between the green (runnable) and red (blocked)
-queues. If you specify the verbose suboption (@-qv@), the green
-queue is split into green (for the currently running thread only) and
-amber (for other runnable threads). We do not recommend that you use
-the verbose suboption if you are planning to use the @hbcpp@
-profiling tools or if you are context switching at every heap check
-(with @-C@).
+(PARALLEL ONLY) Produce a quasi-parallel profile of thread activity,
+in the file @<program>.qp@. In the style of @hbcpp@, this profile
+records the movement of threads between the green (runnable) and red
+(blocked) queues. If you specify the verbose suboption (@-qv@), the
+green queue is split into green (for the currently running thread
+only) and amber (for other runnable threads). We do not recommend
+that you use the verbose suboption if you are planning to use the
+@hbcpp@ profiling tools or if you are context switching at every heap
+check (with @-C@).
<tag>@-t<num>@:</tag>
<nidx>-t<num> RTS option</nidx>
-Limit the number of concurrent threads per processor to @<num>@.
-The default is 32. Each thread requires slightly over 1K <em>words</em>
-in the heap for thread state and stack objects. (For 32-bit machines,
-this translates to 4K bytes, and for 64-bit machines, 8K bytes.)
+(PARALLEL ONLY) Limit the number of concurrent threads per processor
+to @<num>@. The default is 32. Each thread requires slightly over 1K
+<em>words</em> in the heap for thread state and stack objects. (For
+32-bit machines, this translates to 4K bytes, and for 64-bit machines,
+8K bytes.)
<tag>@-d@:</tag>
<nidx>-d RTS option (parallel)</nidx>
appropriate if your machine has a high communication cost relative to
computation speed.
</descrip>
-
-%************************************************************************
-%* *
-<sect2>Potential problems with Parallel Haskell
-<label id="parallel-problems">
-<p>
-<nidx>Parallel Haskell---problems</nidx>
-<nidx>problems, Parallel Haskell</nidx>
-%* *
-%************************************************************************
-
-The ``Potential problems'' for Concurrent Haskell also apply for
-Parallel Haskell. Please see Section <ref name="Potential problems with Concurrent Haskell" id="concurrent-problems">.
projects / ghc-hetmet.git / blobdiff