ghc/docs/users_guide/parallel.lit

   1 % both concurrent and parallel
   2 %************************************************************************
   3 %*                                                                      *
   4 \section[concurrent-and-parallel]{Concurrent and Parallel Haskell}
   5 \index{Concurrent Haskell}
   6 \index{Parallel Haskell}
   7 %*                                                                      *
   8 %************************************************************************
   9
  10 Concurrent and Parallel Haskell are Glasgow extensions to Haskell
  11 which let you structure your program as a group of independent
  12 `threads'.
  13
  14 Concurrent and Parallel Haskell have very different purposes.
  15
  16 Concurrent Haskell is for applications which have an inherent
  17 structure of interacting, concurrent tasks (i.e. `threads').  Threads
  18 in such programs may be {\em required}.  For example, if a concurrent
  19 thread has been spawned to handle a mouse click, it isn't
  20 optional---the user wants something done!
  21
  22 A Concurrent Haskell program implies multiple `threads' running within
  23 a single Unix process on a single processor.
  24
  25 You will find at least one paper about Concurrent Haskell hanging off
  26 of Simon Peyton Jones's Web page;
  27 \tr{http://www.dcs.gla.ac.uk/~simonpj/}.
  28
  29 Parallel Haskell is about {\em speed}---spawning threads onto multiple
  30 processors so that your program will run faster.  The `threads'
  31 are always {\em advisory}---if the runtime system thinks it can
  32 get the job done more quickly by sequential execution, then fine.
  33
  34 A Parallel Haskell program implies multiple processes running on
  35 multiple processors, under a PVM (Parallel Virtual Machine) framework.
  36
  37 Parallel Haskell is still relatively new; it is more about ``research
  38 fun'' than about ``speed.'' That will change.
  39
  40 Again, check Simon's Web page for publications about Parallel Haskell
  41 (including ``GUM'', the key bits of the runtime system).
  42
  43 Some details about Concurrent and Parallel Haskell follow.
  44
  45 %************************************************************************
  46 %*                                                                      *
  47 \subsection{Concurrent and Parallel Haskell---language features}
  48 \index{Concurrent Haskell---features}
  49 \index{Parallel Haskell---features}
  50 %*                                                                      *
  51 %************************************************************************
  52
  53 %************************************************************************
  54 %*                                                                      *
  55 \subsubsection{Features specific to Concurrent Haskell}
  56 %*                                                                      *
  57 %************************************************************************
  58
  59 %************************************************************************
  60 %*                                                                      *
  61 \subsubsubsection{The \tr{Concurrent} interface (recommended)}
  62 \index{Concurrent interface}
  63 %*                                                                      *
  64 %************************************************************************
  65
  66 GHC provides a \tr{Concurrent} module, a common interface to a
  67 collection of useful concurrency abstractions, including those
  68 mentioned in the ``concurrent paper''.
  69
  70 Just put \tr{import Concurrent} into your modules, and away you go.
  71 To create a ``required thread'':
  72
  73 \begin{verbatim}
  74 forkIO :: IO a -> IO a
  75 \end{verbatim}
  76
  77 The \tr{Concurrent} interface also provides access to ``I-Vars''
  78 and ``M-Vars'', which are two flavours of {\em synchronising variables}.
  79 \index{synchronising variables (Glasgow extension)}
  80 \index{concurrency -- synchronising variables}
  81
  82 \tr{IVars}\index{IVars (Glasgow extension)} are write-once
  83 variables.  They start out empty, and any threads that attempt to read
  84 them will block until they are filled.  Once they are written, any
  85 blocked threads are freed, and additional reads are permitted.
  86 Attempting to write a value to a full \tr{IVar} results in a runtime
  87 error.  Interface:
  88 \begin{verbatim}
  89 newIVar     :: IO (IVar a)
  90 readIVar    :: IVar a -> IO a
  91 writeIVar   :: IVar a -> a -> IO ()
  92 \end{verbatim}
  93
  94 \tr{MVars}\index{MVars (Glasgow extension)} are rendezvous points,
  95 mostly for concurrent threads.  They begin empty, and any attempt to
  96 read an empty \tr{MVar} blocks.  When an \tr{MVar} is written, a
  97 single blocked thread may be freed.  Reading an \tr{MVar} toggles its
  98 state from full back to empty.  Therefore, any value written to an
  99 \tr{MVar} may only be read once.  Multiple reads and writes are
 100 allowed, but there must be at least one read between any two
 101 writes. Interface:
 102 \begin{verbatim}
 103 newEmptyMVar :: IO (MVar a)
 104 newMVar      :: a -> IO (MVar a)
 105 takeMVar     :: MVar a -> IO a
 106 putMVar      :: MVar a -> a -> IO ()
 107 readMVar     :: MVar a -> IO a
 108 swapMVar     :: MVar a -> a -> IO a
 109 \end{verbatim}
 110
 111 A {\em channel variable} (@CVar@) is a one-element channel, as
 112 described in the paper:
 113
 114 \begin{verbatim}
 115 data CVar a
 116 newCVar :: IO (CVar a)
 117 putCVar :: CVar a -> a -> IO ()
 118 getCVar :: CVar a -> IO a
 119 \end{verbatim}
 120
 121 A @Channel@ is an unbounded channel:
 122
 123 \begin{verbatim}
 124 data Chan a
 125 newChan         :: IO (Chan a)
 126 putChan         :: Chan a -> a -> IO ()
 127 getChan         :: Chan a -> IO a
 128 dupChan         :: Chan a -> IO (Chan a)
 129 unGetChan       :: Chan a -> a -> IO ()
 130 getChanContents :: Chan a -> IO [a]
 131 \end{verbatim}
 132
 133 General and quantity semaphores:
 134
 135 \begin{verbatim}
 136 data QSem
 137 newQSem     :: Int   -> IO QSem
 138 waitQSem    :: QSem  -> IO ()
 139 signalQSem  :: QSem  -> IO ()
 140
 141 data QSemN
 142 newQSemN    :: Int   -> IO QSemN
 143 signalQSemN :: QSemN -> Int -> IO ()
 144 waitQSemN   :: QSemN -> Int -> IO ()
 145 \end{verbatim}
 146
 147 Merging streams---binary and n-ary:
 148
 149 \begin{verbatim}
 150 mergeIO  :: [a]   -> [a] -> IO [a]
 151 nmergeIO :: [[a]] -> IO [a]
 152 \end{verbatim}
 153
 154 A {\em Sample variable} (@SampleVar@) is slightly different from a
 155 normal @MVar@:
 156 \begin{itemize}
 157 \item Reading an empty @SampleVar@ causes the reader to block
 158     (same as @takeMVar@ on empty @MVar@).
 159 \item Reading a filled @SampleVar@ empties it and returns value.
 160     (same as @takeMVar@)
 161 \item Writing to an empty @SampleVar@ fills it with a value, and
 162 potentially, wakes up a blocked reader  (same as for @putMVar@ on empty @MVar@).
 163 \item Writing to a filled @SampleVar@ overwrites the current value.
 164  (different from @putMVar@ on full @MVar@.)
 165 \end{itemize}
 166
 167 \begin{verbatim}
 168 type SampleVar a = MVar (Int, MVar a)
 169
 170 emptySampleVar :: SampleVar a -> IO ()
 171 newSampleVar   :: IO (SampleVar a)
 172 readSample     :: SampleVar a -> IO a
 173 writeSample    :: SampleVar a -> a -> IO ()
 174 \end{verbatim}
 175
 176 Finally, there are operations to delay a concurrent thread, and to
 177 make one wait:\index{delay a concurrent thread}
 178 \index{wait for a file descriptor}
 179 \begin{verbatim}
 180 threadDelay :: Int -> IO () -- delay rescheduling for N microseconds
 181 threadWait  :: Int -> IO () -- wait for input on specified file descriptor
 182 \end{verbatim}
 183
 184 %************************************************************************
 185 %*                                                                      *
 186 \subsubsection{Features specific to Parallel Haskell}
 187 %*                                                                      *
 188 %************************************************************************
 189
 190 %************************************************************************
 191 %*                                                                      *
 192 \subsubsubsection{The \tr{Parallel} interface (recommended)}
 193 \index{Parallel interface}
 194 %*                                                                      *
 195 %************************************************************************
 196
 197 GHC provides two functions for controlling parallel execution, through
 198 the \tr{Parallel} interface:
 199 \begin{verbatim}
 200 interface Parallel where
 201 infixr 0 `par`
 202 infixr 1 `seq`
 203
 204 par :: a -> b -> b
 205 seq :: a -> b -> b
 206 \end{verbatim}
 207
 208 The expression \tr{(x `par` y)} {\em sparks} the evaluation of \tr{x}
 209 (to weak head normal form) and returns \tr{y}.  Sparks are queued for
 210 execution in FIFO order, but are not executed immediately.  At the
 211 next heap allocation, the currently executing thread will yield
 212 control to the scheduler, and the scheduler will start a new thread
 213 (until reaching the active thread limit) for each spark which has not
 214 already been evaluated to WHNF.
 215
 216 The expression \tr{(x `seq` y)} evaluates \tr{x} to weak head normal
 217 form and then returns \tr{y}.  The \tr{seq} primitive can be used to
 218 force evaluation of an expression beyond WHNF, or to impose a desired
 219 execution sequence for the evaluation of an expression.
 220
 221 For example, consider the following parallel version of our old
 222 nemesis, \tr{nfib}:
 223
 224 \begin{verbatim}
 225 import Parallel
 226
 227 nfib :: Int -> Int
 228 nfib n | n <= 1 = 1
 229        | otherwise = par n1 (seq n2 (n1 + n2 + 1))
 230                      where n1 = nfib (n-1)
 231                            n2 = nfib (n-2)
 232 \end{verbatim}
 233
 234 For values of \tr{n} greater than 1, we use \tr{par} to spark a thread
 235 to evaluate \tr{nfib (n-1)}, and then we use \tr{seq} to force the
 236 parent thread to evaluate \tr{nfib (n-2)} before going on to add
 237 together these two subexpressions.  In this divide-and-conquer
 238 approach, we only spark a new thread for one branch of the computation
 239 (leaving the parent to evaluate the other branch).  Also, we must use
 240 \tr{seq} to ensure that the parent will evaluate \tr{n2} {\em before}
 241 \tr{n1} in the expression \tr{(n1 + n2 + 1)}.  It is not sufficient to
 242 reorder the expression as \tr{(n2 + n1 + 1)}, because the compiler may
 243 not generate code to evaluate the addends from left to right.
 244
 245 %************************************************************************
 246 %*                                                                      *
 247 \subsubsubsection{Underlying functions and primitives}
 248 \index{parallelism primitives}
 249 \index{primitives for parallelism}
 250 %*                                                                      *
 251 %************************************************************************
 252
 253 The functions \tr{par} and \tr{seq} are wired into GHC, and unfold
 254 into uses of the \tr{par#} and \tr{seq#} primitives, respectively.  If
 255 you'd like to see this with your very own eyes, just run GHC with the
 256 \tr{-ddump-simpl} option.  (Anything for a good time...)
 257
 258 You can use \tr{par} and \tr{seq} in Concurrent Haskell, though
 259 I'm not sure why you would want to.
 260
 261 %************************************************************************
 262 %*                                                                      *
 263 \subsubsection{Features common to Concurrent and Parallel Haskell}
 264 %*                                                                      *
 265 %************************************************************************
 266
 267 Actually, you can use the \tr{`par`} and \tr{`seq`} combinators
 268 (really for Parallel Haskell) in Concurrent Haskell as well.
 269 But doing things like ``\tr{par} to \tr{forkIO} many required threads''
 270 counts as ``jumping out the 9th-floor window, just to see what happens.''
 271
 272 %************************************************************************
 273 %*                                                                      *
 274 \subsubsubsection{Scheduling policy for concurrent/parallel threads}
 275 \index{Scheduling---concurrent/parallel}
 276 \index{Concurrent/parallel scheduling}
 277 %*                                                                      *
 278 %************************************************************************
 279
 280 Runnable threads are scheduled in round-robin fashion.  Context
 281 switches are signalled by the generation of new sparks or by the
 282 expiry of a virtual timer (the timer interval is configurable with the
 283 \tr{-C[<num>]}\index{-C<num> RTS option (concurrent, parallel)} RTS option).
 284 However, a context switch doesn't really happen until the next heap
 285 allocation.  If you want extremely short time slices, the \tr{-C} RTS
 286 option can be used to force a context switch at each and every heap
 287 allocation.
 288
 289 When a context switch occurs, pending sparks which have not already
 290 been reduced to weak head normal form are turned into new threads.
 291 However, there is a limit to the number of active threads (runnable or
 292 blocked) which are allowed at any given time.  This limit can be
 293 adjusted with the \tr{-t<num>}\index{-t <num> RTS option (concurrent, parallel)}
 294 RTS option (the default is 32).  Once the
 295 thread limit is reached, any remaining sparks are deferred until some
 296 of the currently active threads are completed.
 297
 298 %************************************************************************
 299 %*                                                                      *
 300 \subsection{How to use Concurrent and Parallel Haskell}
 301 %*                                                                      *
 302 %************************************************************************
 303
 304 [You won't get far unless your GHC system was configured/built with
 305 concurrency and/or parallelism enabled.  (They require separate
 306 library modules.)  The relevant section of the installation guide says
 307 how to do this.]
 308
 309 %************************************************************************
 310 %*                                                                      *
 311 \subsubsection{Using Concurrent Haskell}
 312 \index{Concurrent Haskell---use}
 313 %*                                                                      *
 314 %************************************************************************
 315
 316 To compile a program as Concurrent Haskell, use the \tr{-concurrent}
 317 option,\index{-concurrent option} both when compiling {\em and
 318 linking}.  You will probably need the \tr{-fglasgow-exts} option, too.
 319
 320 Three RTS options are provided for modifying the behaviour of the
 321 threaded runtime system.  See the descriptions of \tr{-C[<us>]}, \tr{-q},
 322 and \tr{-t<num>} in \Sectionref{parallel-rts-opts}.
 323
 324 %************************************************************************
 325 %*                                                                      *
 326 \subsubsubsection[concurrent-problems]{Potential problems with Concurrent Haskell}
 327 \index{Concurrent Haskell problems}
 328 \index{problems, Concurrent Haskell}
 329 %*                                                                      *
 330 %************************************************************************
 331
 332 The main thread in a Concurrent Haskell program is given its own
 333 private stack space, but all other threads are given stack space from
 334 the heap.  Stack space for the main thread can be
 335 adjusted as usual with the \tr{-K} RTS
 336 option,\index{-K RTS option (concurrent, parallel)} but if this
 337 private stack space is exhausted, the main thread will switch to stack
 338 segments in the heap, just like any other thread.  Thus, problems
 339 which would normally result in stack overflow in ``sequential Haskell''
 340 can be expected to result in heap overflow when using threads.
 341
 342 The concurrent runtime system uses black holes as synchronisation
 343 points for subexpressions which are shared among multiple threads.  In
 344 ``sequential Haskell'', a black hole indicates a cyclic data
 345 dependency, which is a fatal error.  However, in concurrent execution, a
 346 black hole may simply indicate that the desired expression is being
 347 evaluated by another thread.  Therefore, when a thread encounters a
 348 black hole, it simply blocks and waits for the black hole to be
 349 updated.  Cyclic data dependencies will result in deadlock, and the
 350 program will fail to terminate.
 351
 352 Because the concurrent runtime system uses black holes as
 353 synchronisation points, it is not possible to disable black-holing
 354 with the \tr{-N} RTS option.\index{-N RTS option} Therefore, the use
 355 of signal handlers (including timeouts) with the concurrent runtime
 356 system can lead to problems if a thread attempts to enter a black hole
 357 that was created by an abandoned computation.  The use of signal
 358 handlers in conjunction with threads is strongly discouraged.
 359
 360
 361 %************************************************************************
 362 %*                                                                      *
 363 \subsubsection{Using Parallel Haskell}
 364 \index{Parallel Haskell---use}
 365 %*                                                                      *
 366 %************************************************************************
 367
 368 [You won't be able to execute parallel Haskell programs unless PVM3
 369 (Parallel Virtual Machine, version 3) is installed at your site.]
 370
 371 To compile a Haskell program for parallel execution under PVM, use the
 372 \tr{-parallel} option,\index{-parallel option} both when compiling
 373 {\em and linking}.  You will probably want to \tr{import Parallel}
 374 into your Haskell modules.
 375
 376 To run your parallel program, once PVM is going, just invoke it ``as
 377 normal''.  The main extra RTS option is \tr{-N<n>}, to say how many
 378 PVM ``processors'' your program to run on.  (For more details of
 379 all relevant RTS options, please see \sectionref{parallel-rts-opts}.)
 380
 381 In truth, running Parallel Haskell programs and getting information
 382 out of them (e.g., parallelism profiles) is a battle with the vagaries of
 383 PVM, detailed in the following sections.
 384
 385 %************************************************************************
 386 %*                                                                      *
 387 \subsubsubsection{Dummy's guide to using PVM}
 388 \index{PVM, how to use}
 389 \index{Parallel Haskell---PVM use}
 390 %*                                                                      *
 391 %************************************************************************
 392
 393 Before you can run a parallel program under PVM, you must set the
 394 required environment variables (PVM's idea, not ours); something like,
 395 probably in your \tr{.cshrc} or equivalent:
 396 \begin{verbatim}
 397 setenv PVM_ROOT /wherever/you/put/it
 398 setenv PVM_ARCH `$PVM_ROOT/lib/pvmgetarch`
 399 setenv PVM_DPATH $PVM_ROOT/lib/pvmd
 400 \end{verbatim}
 401
 402 Creating and/or controlling your ``parallel machine'' is a purely-PVM
 403 business; nothing specific to Parallel Haskell.
 404
 405 You use the \tr{pvm}\index{pvm command} command to start PVM on your
 406 machine.  You can then do various things to control/monitor your
 407 ``parallel machine;'' the most useful being:
 408
 409 \begin{tabular}{ll}
 410 \tr{Control-D} & exit \tr{pvm}, leaving it running \\
 411 \tr{halt} & kill off this ``parallel machine'' \& exit \\
 412 \tr{add <host>} & add \tr{<host>} as a processor \\
 413 \tr{delete <host>} & delete \tr{<host>} \\
 414 \tr{reset}      & kill what's going, but leave PVM up \\
 415 \tr{conf}       & list the current configuration \\
 416 \tr{ps}         & report processes' status \\
 417 \tr{pstat <pid>} & status of a particular process \\
 418 \end{tabular}
 419
 420 The PVM documentation can tell you much, much more about \tr{pvm}!
 421
 422 %************************************************************************
 423 %*                                                                      *
 424 \subsubsection{Parallelism profiles}
 425 \index{parallelism profiles}
 426 \index{profiles, parallelism}
 427 \index{visualisation tools}
 428 %*                                                                      *
 429 %************************************************************************
 430
 431 With Parallel Haskell programs, we usually don't care about the
 432 results---only with ``how parallel'' it was!  We want pretty pictures.
 433
 434 Parallelism profiles (\`a la \tr{hbcpp}) can be generated with the
 435 \tr{-q}\index{-q RTS option (concurrent, parallel)} RTS option.  The
 436 per-processor profiling info is dumped into files named
 437 \tr{<full-path><program>.gr}.  These are then munged into a PostScript picture,
 438 which you can then display.  For example, to run your program
 439 \tr{a.out} on 8 processors, then view the parallelism profile, do:
 440
 441 \begin{verbatim}
 442 % ./a.out +RTS -N8 -q
 443 % grs2gr *.???.gr > temp.gr     # combine the 8 .gr files into one
 444 % gr2ps -O temp.gr              # cvt to .ps; output in temp.ps
 445 % ghostview -seascape temp.ps   # look at it!
 446 \end{verbatim}
 447
 448 The scripts for processing the parallelism profiles are distributed
 449 in \tr{ghc/utils/parallel/}.
 450
 451 %$$************************************************************************
 452 %$$*                                                                      *
 453 %$$\subsubsection{Activity profiles}
 454 %$$\index{activity profiles}
 455 %$$\index{profiles, activity}
 456 %$$\index{visualisation tools}
 457 %$$%$$*                                                                      *
 458 %$$%$$************************************************************************
 459 %$$
 460 %$$You can also use the standard GHC ``cost-centre'' profiling to see how
 461 %$$much time each PVM ``processor'' spends
 462 %$$
 463 %$$No special compilation flags beyond \tr{-parallel} are required to get
 464 %$$this basic four-activity profile.  Just use the \tr{-P} RTS option,
 465 %$$thusly:
 466 %$$\begin{verbatim}
 467 %$$./a.out +RTS -N7 -P  # 7 processors
 468 %$$\end{verbatim}
 469 %$$
 470 %$$The above will create files named \tr{<something>.prof} and/or
 471 %$$\tr{<something>.time} {\em in your home directory}.  You can
 472 %$$process the \tr{.time} files into PostScript using \tr{hp2ps},
 473 %$$\index{hp2ps}
 474 %$$as described elsewhere in this guide.
 475 %$$
 476 %$$Because of the weird file names, you probably need to use
 477 %$$\tr{hp2ps} as a filter.  Also, you probably want to give \tr{hp2ps}
 478 %$$a \tr{-t0} flag, so that no ``inconsequential'' data is ignored---in
 479 %$$parallel-land it's all consequential.  So:
 480 %$$\begin{verbatim}
 481 %$$%$$ hp2ps -t0 < fooo.001.time > temp.ps
 482 %$$\end{verbatim}
 483 %$$
 484 %$$ The first line of the
 485 %$$ \tr{.qp} file contains the name of the program executed, along with
 486 %$$ any program arguments and thread-specific RTS options.  The second
 487 %$$ line contains the date and time of program execution.  The third
 488 %$$ and subsequent lines contain information about thread state transitions.
 489 %$$
 490 %$$ The thread state transition lines have the following format:
 491 %$$ \begin{verbatim}
 492 %$$ time transition thread-id thread-name [thread-id thread-name]
 493 %$$ \end{verbatim}
 494 %$$
 495 %$$ The \tr{time} is the virtual time elapsed since the program started
 496 %$$ execution, in milliseconds.  The \tr{transition} is a two-letter code
 497 %$$ indicating the ``from'' queue and the ``to'' queue, where each queue
 498 %$$ is one of:
 499 %$$ \begin{itemize}
 500 %$$ \item[\tr{*}] Void: Thread creation or termination.
 501 %$$ \item[\tr{G}] Green: Runnable (or actively running, with \tr{-qv}) threads.
 502 %$$ \item[\tr{A}] Amber: Runnable threads (\tr{-qv} only).
 503 %$$ \item[\tr{R}] Red: Blocked threads.
 504 %$$ \end{itemize}
 505 %$$ The \tr{thread-id} is a unique integer assigned to each thread.  The
 506 %$$ \tr{thread-name} is currently the address of the thread's root closure
 507 %$$ (in hexadecimal).  In the future, it will be the name of the function
 508 %$$ associated with the root of the thread.
 509 %$$
 510 %$$ The first \tr{(thread-id, thread-name)} pair identifies the thread
 511 %$$ involved in the indicated transition.  For \tr{RG} and \tr{RA} transitions
 512 %$$ only, there is a second \tr{(thread-id, thread-name)} pair which identifies
 513 %$$ the thread that released the blocked thread.
 514 %$$
 515 %$$ Provided with the GHC distribution is a perl script, \tr{qp2pp}, which
 516 %$$ will convert \tr{.qp} files to \tr{hbcpp}'s \tr{.pp} format, so that
 517 %$$ you can use the \tr{hbcpp} profiling tools, such as \tr{pp2ps92}.  The
 518 %$$ \tr{.pp} format has undergone many changes, so the conversion script
 519 %$$ is not compatible with earlier releases of \tr{hbcpp}.  Note that GHC
 520 %$$ and \tr{hbcpp} use different thread scheduling policies (in
 521 %$$ particular, \tr{hbcpp} threads never move from the green queue to the
 522 %$$ amber queue).  For compatibility, the \tr{qp2pp} script eliminates the
 523 %$$ GHC amber queue, so there is no point in using the verbose (\tr{-qv})
 524 %$$ option if you are only interested in using the \tr{hbcpp} profiling
 525 %$$ tools.
 526
 527 %************************************************************************
 528 %*                                                                      *
 529 \subsubsection{Other useful info about running parallel programs}
 530 %*                                                                      *
 531 %************************************************************************
 532
 533 The ``garbage-collection statistics'' RTS options can be useful for
 534 seeing what parallel programs are doing.  If you do either
 535 \tr{+RTS -Sstderr}\index{-Sstderr RTS option} or \tr{+RTS -sstderr}, then
 536 you'll get mutator, garbage-collection, etc., times on standard
 537 error. The standard error of all PE's other than the `main thread'
 538 appears in \tr{/tmp/pvml.nnn}, courtesy of PVM.
 539
 540 Whether doing \tr{+RTS -Sstderr} or not, a handy way to watch
 541 what's happening overall is: \tr{tail -f /tmp/pvml.nnn}.
 542
 543 %************************************************************************
 544 %*                                                                      *
 545 \subsubsection[parallel-rts-opts]{RTS options for Concurrent/Parallel Haskell}
 546 \index{RTS options, concurrent}
 547 \index{RTS options, parallel}
 548 \index{Concurrent Haskell---RTS options}
 549 \index{Parallel Haskell---RTS options}
 550 %*                                                                      *
 551 %************************************************************************
 552
 553 Besides the usual runtime system (RTS) options
 554 (\sectionref{runtime-control}), there are a few options particularly
 555 for concurrent/parallel execution.
 556
 557 \begin{description}
 558 \item[\tr{-N<N>}:]
 559 \index{-N<N> RTS option (parallel)}
 560 (PARALLEL ONLY) Use \tr{<N>} PVM processors to run this program;
 561 the default is 2.
 562
 563 \item[\tr{-C[<us>]}:]
 564 \index{-C<us> RTS option}
 565 Sets the context switch interval to \pl{<us>} microseconds.  A context
 566 switch will occur at the next heap allocation after the timer expires.
 567 With \tr{-C0} or \tr{-C}, context switches will occur as often as
 568 possible (at every heap allocation).  By default, context switches
 569 occur every 10 milliseconds.  Note that many interval timers are only
 570 capable of 10 millisecond granularity, so the default setting may be
 571 the finest granularity possible, short of a context switch at every
 572 heap allocation.
 573
 574 \item[\tr{-q[v]}:]
 575 \index{-q RTS option}
 576 Produce a quasi-parallel profile of thread activity, in the file
 577 \tr{<program>.qp}.  In the style of \tr{hbcpp}, this profile records
 578 the movement of threads between the green (runnable) and red (blocked)
 579 queues.  If you specify the verbose suboption (\tr{-qv}), the green
 580 queue is split into green (for the currently running thread only) and
 581 amber (for other runnable threads).  We do not recommend that you use
 582 the verbose suboption if you are planning to use the \tr{hbcpp}
 583 profiling tools or if you are context switching at every heap check
 584 (with \tr{-C}).
 585
 586 \item[\tr{-t<num>}:]
 587 \index{-t<num> RTS option}
 588 Limit the number of concurrent threads per processor to \pl{<num>}.
 589 The default is 32.  Each thread requires slightly over 1K {\em words}
 590 in the heap for thread state and stack objects.  (For 32-bit machines,
 591 this translates to 4K bytes, and for 64-bit machines, 8K bytes.)
 592
 593 \item[\tr{-d}:]
 594 \index{-d RTS option (parallel)}
 595 (PARALLEL ONLY) Turn on debugging.  It pops up one xterm (or GDB, or
 596 something...) per PVM processor.  We use the standard \tr{debugger}
 597 script that comes with PVM3, but we sometimes meddle with the
 598 \tr{debugger2} script.  We include ours in the GHC distribution,
 599 in \tr{ghc/utils/pvm/}.
 600
 601 \item[\tr{-e<num>}:]
 602 \index{-e<num> RTS option (parallel)}
 603 (PARALLEL ONLY) Limit the number of pending sparks per processor to
 604 \tr{<num>}. The default is 100. A larger number may be appropriate if
 605 your program generates large amounts of parallelism initially.
 606
 607 \item[\tr{-Q<num>}:]
 608 \index{-Q<num> RTS option (parallel)}
 609 (PARALLEL ONLY) Set the size of packets transmitted between processors
 610 to \tr{<num>}. The default is 1024 words. A larger number may be
 611 appropriate if your machine has a high communication cost relative to
 612 computation speed.
 613 \end{description}
 614
 615 %************************************************************************
 616 %*                                                                      *
 617 \subsubsubsection[parallel-problems]{Potential problems with Parallel Haskell}
 618 \index{Parallel Haskell---problems}
 619 \index{problems, Parallel Haskell}
 620 %*                                                                      *
 621 %************************************************************************
 622
 623 The ``Potential problems'' for Concurrent Haskell also apply for
 624 Parallel Haskell.  Please see \Sectionref{concurrent-problems}.
 625
 626 %$$ \subsubsubsection[par-notes]{notes for 0.26}
 627 %$$
 628 %$$ \begin{verbatim}
 629 %$$ Install PVM somewhere, as it says.  We use 3.3
 630 %$$
 631 %$$ pvm.h : can do w/ a link from ghc/includes to its true home (???)
 632 %$$
 633 %$$
 634 %$$ ghc -gum ... => a.out
 635 %$$
 636 %$$     a.out goes to $PVM_ROOT/bin/$PVM_ARCH/$PE
 637 %$$
 638 %$$     (profiling outputs go to ~/$PE.<process-num>.<suffix>)
 639 %$$
 640 %$$     trinder scripts in: ~trinder/bin/any/instPHIL
 641 %$$
 642 %$$ To run:
 643 %$$
 644 %$$     Then:
 645 %$$     SysMan [-] N (PEs) args-to-program...
 646 %$$
 647 %$$         - ==> debug mode
 648 %$$                 mattson setup: GDB window per task
 649 %$$                 /local/grasp_tmp5/mattson/pvm3/lib/debugger{,2}
 650 %$$
 651 %$$                 to set breakpoint, etc, before "run", just modify debugger2
 652 %$$
 653 %$$     stderr and stdout are directed to /tmp/pvml.NNN
 654 %$$
 655 %$$ Visualisation stuff (normal _mp build):
 656 %$$
 657 %$$ +RTS -q         gransim-like profiling
 658 %$$                 (should use exactly-gransim RTS options)
 659 %$$      -qb        binary dumps : not tried, not recommended: hosed!
 660 %$$
 661 %$$     ascii dump : same info as gransim, one extra line at top w/
 662 %$$                 start time; all times are ms since then
 663 %$$
 664 %$$     dumps appear in $HOME/<program>.nnn.gr
 665 %$$
 666 %$$ ~mattson/grs2gr.pl == combine lots into one (fixing times)
 667 %$$
 668 %$$ /local/grasp/hwloidl/GrAn/bin/ is where scripts are.
 669 %$$
 670 %$$ gr2ps == activity profile (bash script)
 671 %$$
 672 %$$ ~mattson/bin/`arch`/gr2qp must be picked up prior to hwloidl's for
 673 %$$ things to work...
 674 %$$
 675 %$$ +RTS -[Pp]      (parallel) 4-cost-centre "profiling" (gc,MAIN,msg,idle)
 676 %$$
 677 %$$         ToDos: time-profiles from hp2ps: something about zeroth sample;
 678 %$$ \end{verbatim}