X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fusing.xml;h=d6eb6ed30183ff2d702c8b886550b5fdafbe9d29;hb=a1497e61c767a1d73c8e8c9ccb017b8bce270dee;hp=4b3024ae9b945f6468cb3beb3dac8f72e9d3ae3c;hpb=cae75f82226638691cfa1e85fc168f4b65ddce4d;p=ghc-hetmet.git diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml index 4b3024a..d6eb6ed 100644 --- a/docs/users_guide/using.xml +++ b/docs/users_guide/using.xml @@ -46,26 +46,25 @@ ghc [argument...] Sometimes it is useful to make the connection between a source file and the command-line options it requires quite - tight. For instance, if a Haskell source file uses GHC - extensions, it will always need to be compiled with the - option. Rather than maintaining + tight. For instance, if a Haskell source file deliberately + uses name shadowing, it should be compiled with the + option. Rather than maintaining the list of per-file options in a Makefile, it is possible to do this directly in the source file using the OPTIONS_GHC pragma OPTIONS_GHC pragma: -{-# OPTIONS_GHC -fglasgow-exts #-} +{-# OPTIONS_GHC -fno-warn-name-shadowing #-} module X where ... - OPTIONS_GHC pragmas are only looked for at - the top of your source files, upto the first - (non-literate,non-empty) line not containing - OPTIONS_GHC. Multiple OPTIONS_GHC - pragmas are recognised. Do not put comments before, or on the same line - as, the OPTIONS_GHC pragma. + OPTIONS_GHC is a file-header pragma + (see ). + + Only dynamic flags can be used in an OPTIONS_GHC pragma + (see ). Note that your command shell does not get to the source file options, they are just included literally @@ -1179,7 +1178,8 @@ f foo = foo { x = 6 } The trouble with orphans is that GHC must pro-actively read the interface files for all orphan modules, just in case their instances or rules play a role, whether or not the module's interface would otherwise - be of any use. Other things being equal, avoid orphan modules. + be of any use. See for details. + @@ -1764,15 +1764,58 @@ f "2" = 2 linkend="lang-parallel" /> we describe the language features that affect parallelism. - - Options for SMP parallelism + + Compile-time options for SMP parallelism In order to make use of multiple CPUs, your program must be linked with the option (see ). Then, to run a program on multiple - CPUs, use the RTS option: + linkend="options-linker" />). Additionally, the following + compiler options affect parallelism: + + + + + + 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 NonTermination + exception), secondly it avoids certain kinds of space + leak, and thirdly it avoids repeating a computation in a + parallel program, because we can tell when a computation + is already in progress. + + + The option 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 is typically more + efficient (by 1-2% or so), because most thunks don't + need to be blackholed. However, eager blackholing can + avoid more repeated computation in a parallel program, and + this often turns out to be important for parallelism. + + + + We recommend compiling any code that is intended to be run + in parallel with the + flag. + + + + + + + + RTS options for SMP parallelism + + To run a program on multiple CPUs, use the + RTS option: + + @@ -1905,7 +1948,7 @@ statements or clauses. GHC can dump its optimized intermediate code (said to be in “Core” format) to a file as a side-effect of compilation. Non-GHC back-end tools can read and process Core files; these files have the suffix - .hcr. The Core format is described in + .hcr. The Core format is described in An External Representation for the GHC Core Language, and sample tools for manipulating Core files (in Haskell) are in the GHC source distribution