Revert rename of dph-common for now
[packages/dph.git] / dph-common / README
1 NDP library
2 ===========
3
4 Home:             http://haskell.org/haskellwiki/GHC/Data_Parallel_Haskell
5 Darcs repository: http://darcs.haskell.org/packages/ndp
6
7 Building
8 --------
9
10 The NDP library works ONLY with GHC. You really want to use HEAD, which
11 includes many improvements to the simplifier which are crucial for good
12 performance.
13
14 The recommended way to build the NDP library is by building the latest GHC
15 from the darcs repository (http://hackage.haskell.org/trac/ghc/wiki/Building),
16 then unpacking the sources (or, preferably, getting the latest version from
17 the darcs repository) in ghc/libraries and then doing
18
19 cd ndp
20 make boot
21 make
22 cd examples
23 make
24
25 Writing NDP programs
26 --------------------
27
28 Import Data.Array.Parallel.Unlifted (sequential combinators) and/or
29 Data.Array.Parallel.Unlifted.Parallel (parallel combinators). The subdirectory
30 examples contains several NDP programs.
31
32 Before invoking any parallel combinators you must initialise the gang threads,
33 usually by calling
34
35   Data.Array.Parallel.Unlifted.Distributed.setGang <T>
36
37 where T is the number of threads. Normally, you want to run the program with
38 +RTS -N<T> as well as you won't get any parallelism otherwise. This is a
39 regrettable hack which will go away eventually.
40
41 Compiling NDP programs
42 ----------------------
43
44 The file ndp.mk shows the options you'll usually want for compiling NDP
45 programs. You don't need -fbang-patterns unless you actually use them. You
46 might get away with omitting -fmax-simplifier-iterations6; however, sometimes
47 GHC will really need that many iterations to fully optimise NDP programs.
48
49 NDP on NUMA machines
50 --------------------
51
52 NUMA machines, for instance multiprocessors based on AMD Opterons, might
53 benefit from interleaved memory allocation. Under Linux, this can be achieved
54 by running
55
56   numactl --interleave=all <cmd>
57
58 where cmd is the NDP program you want to run. Also, explicitly setting the
59 processor affinity (taskset in Linux) might be helpful.
60
61 Implemented functionality
62 -------------------------
63
64 At the moment, the library only really supports flat arrays. Segmented arrays
65 are provided but you must really know what you are doing to get efficient
66 code. A lot of combinators (especially for segmented arrays) are still
67 missing.
68
69 Haddock documentation
70 ---------------------
71
72 Haddock doesn't support various language features used by the library at the
73 moment and can't be used to generate documentation. In principle, haddock.ghc
74 from http://darcs.haskell.org/SoC/haddock.ghc should be able to process the
75 library but it doesn't work for me at the moment.
76