[m-rev.] For review: Document parallelism related features.

[Paul Bone]

On Fri, Feb 26, 2010 at 08:02:06PM +1100, Julien Fischer wrote:
> On Tue, 23 Feb 2010, Paul Bone wrote:
> > Document parallelism related features.
> >
> > This changeset adds/uncomments documentation for the parallel grade, parallel
> > conjunction and threadscope grade.
> >
> > compiler/options.m:
> >     Document the --parallel and --threadscope options (and grade modifiers).
> >
> > doc/reference_manual.texi:
> >     Document the parallel conjunction and it's optional operational semantics.
> >
> >     Note that the parallel conjunction operator is already present in the
> >     operator precedence table.
> >
> > doc/user_guide.texi:
> >     Document the threadscope profiler in the profiling section.
> >
> >     Describe the threadscope and parallel grades in the Grades and Optional
> >     features compilation options sections.
> 
> Could you please post a revised diff once you have addressed Peter's
> comments.
>

Here's the revised changelog and diff, thanks:


Document parallelism related features.

This changeset adds/uncomments documentation for the parallel grade, parallel
conjunction and threadscope grade.

compiler/options.m:
    Document the --parallel and --threadscope options (and grade modifiers).

doc/reference_manual.texi:
    Document the parallel conjunction and it's optional operational semantics.

    Note that the parallel conjunction operator is already present in the
    operator precedence table.

doc/user_guide.texi:
    Document the threadscope profiler in the profiling section.

    Describe the threadscope and parallel grades in the Grades and Optional
    features compilation options sections.

README.Threadscope:
    Create this new file to describe where to get the threadscope tools and
    their dependencies.


Index: README.ThreadScope
===================================================================
RCS file: README.ThreadScope
diff -N README.ThreadScope
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ README.ThreadScope	18 Mar 2010 03:09:24 -0000
@@ -0,0 +1,37 @@
+
+Threadscope Profiling Tools
+---------------------------
+
+Mercury supports threadscope profiling.  See the profiling section in the user
+guide. 
+
+The Threadscope profiling tools are written in Haskell and work with GHC 6.10.
+threadscope has a number of dependencies in the form of Haskell libraries, many
+of these will be provided with GHC or packaged for/by your operating system.
+These are:i
+
+    array
+    binary
+    cairo
+    containers
+    filepath
+    ghc-events
+    glade
+    gtk
+    mtl
+
+Note that the cairo, gtk and glade modules are provided by the gtk2hs package.
+
+ghc-events is not packaged by most operating systems at this stage, It can be
+retrieved from hackage:
+
+    http://hackage.haskell.org/package/ghc-events
+
+threadscope itself can also be retrieved from hackage:
+
+    http://hackage.haskell.org/package/threadscope
+
+Information about how to install Haskell packages can be found here:
+
+    http://haskell.org/haskellwiki/Cabal/How_to_install_a_Cabal_package
+
Index: compiler/options.m
===================================================================
RCS file: /home/mercury1/repository/mercury/compiler/options.m,v
retrieving revision 1.668
diff -u -p -b -r1.668 options.m
--- compiler/options.m	11 Feb 2010 04:36:09 -0000	1.668
+++ compiler/options.m	18 Mar 2010 03:09:24 -0000
@@ -4172,7 +4172,12 @@ options_help_compilation_model -->
         "\tEnable experimental complexity analysis for the predicates",
         "\tlisted in the given file.",
         "\tThis option is supported for the C back-end, with",
-        "\t--no-highlevel-code."
+        "\t--no-highlevel-code.",
+
+        "--threadscope\t\t(grade modifier: `.threadscope')",
+        "\tEnable support for profiling parallel execution.",
+        "\tThis option is supported in the low-level C back-end parallel",
+        "\tgrades on x86 and x86_64 processors."
     ]),
 
     io.write_string("      Miscellaneous optional features\n"),
@@ -4206,6 +4211,9 @@ options_help_compilation_model -->
         "\tAs above, but use a dynamically sized trail that is composed",
         "\tof small segments.  This can help to avoid trail exhaustion",
         "\tat the cost of increased execution time.",
+        "--parallel\t\t(grade modifier: `.par')",
+        "\tEnable parallel execution support.",
+        "\tThis option is only supported for the C back-ends.",
         "--maybe-thread-safe {yes, no}",
         "\tSpecify how to treat the `maybe_thread_safe' foreign code",
         "\tattribute.  `yes' means that a foreign procedure with the",
Index: doc/reference_manual.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/reference_manual.texi,v
retrieving revision 1.439
diff -u -p -b -r1.439 reference_manual.texi
--- doc/reference_manual.texi	15 Mar 2010 17:41:13 -0000	1.439
+++ doc/reference_manual.texi	18 Mar 2010 03:09:24 -0000
@@ -672,6 +672,17 @@ This is an abbreviation for @samp{not (s
 A conjunction.
 @var{Goal1} and @var{Goal2} must be valid goals.
 
+ at item @code{@var{Goal1} & @var{Goal2}}
+A parallel conjunction.
+This has the same declarative semantics as the normal conjunction.
+Operationally, implementations may execute @var{Goal1} & @var{Goal2}
+in parallel.
+Implementations may also start the parallel execution of these goals
+in any order.
+It is a compilation error for @var{Goal1} or @var{Goal2} to have a
+determinism other than @samp{det} or @samp{cc_multi}.  
+ at xref{Determinism categories}.
+
 @item @code{@var{Goal1} ; @var{Goal2}}
 where @var{Goal1} is not of the form @samp{Goal1a -> Goal1b}:
 a disjunction.
Index: doc/user_guide.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/user_guide.texi,v
retrieving revision 1.605
diff -u -p -b -r1.605 user_guide.texi
--- doc/user_guide.texi	15 Mar 2010 05:12:37 -0000	1.605
+++ doc/user_guide.texi	18 Mar 2010 03:09:24 -0000
@@ -5590,6 +5590,8 @@ then a progress message will be displaye
                                     program with mprof.
 * Using mdprof::                    How to analyze the time and/or memory
                                     performance of a program with mdprof.
+* Using threadscope::               How to analyse the parallel
+                                    execution of a program with threadscope.
 * Profiling and shared libraries::  Profiling dynamically linked executables.
 @end menu
 
@@ -5599,6 +5601,7 @@ then a progress message will be displaye
 @cindex Measuring performance
 @cindex Optimization
 @cindex Efficiency
+ at cindex Parallel performance
 
 To obtain the best trade-off between productivity and efficiency,
 programmers should not spend too much time optimizing their code
@@ -5618,19 +5621,34 @@ that associates a lot more context with 
 but not both at the same time;
 @samp{mdprof} can profile both time and space at the same time.
 
+The parallel execution of Mercury programms can be analyzed with a third
+profiler called @samp{threadscope}.
+ at samp{threadscope} allows programmers to visualise CPU utilization,
+as well as how garbage collection, task granularity and the management of
+parallel tasks.
+The @samp{threadscope} tool is not included with the Melbourne Mercury
+Compiler,
+See @url{http://research.microsoft.com/en-us/projects/threadscope/, 
+Threadscope: Peformance Tuning Parallel Haskell Programs}.
+
 @node Building profiled applications
 @section Building profiled applications
 @cindex Building profiled applications
 @pindex mprof
 @pindex mdprof
+ at pindex threadscope
 @cindex Time profiling
 @cindex Heap profiling
 @cindex Memory profiling
 @cindex Allocation profiling
 @cindex Deep profiling
+ at cindex Threadscope profiling
+ at cindex Parallel runtime profiling
+ at findex --parallel
+ at findex --threadscope
 
 To enable profiling, your program must be built with profiling enabled.
-The two different profilers require different support,
+The three different profilers require different support,
 and thus you must choose which one to enable when you build your program.
 
 @itemize @bullet
@@ -5646,6 +5664,10 @@ pass the @samp{--memory-profiling} optio
 To build your program with deep profiling enabled (for @samp{mdprof}),
 pass the @samp{--deep-profiling} option to @samp{mmc},
 @samp{mgnuc} and @samp{ml}.
+ at item
+To build your program with threadscope profiling enabled (for @samp{threadscope}).
+pass the @samp{--parallel --threadscope} options to @samp{mmc},
+ at samp{mgnuc} and @samp{ml}.
 @end itemize
 
 If you are using Mmake,
@@ -5655,7 +5677,7 @@ e.g.@: by adding the line @samp{GRADEFLA
 (For more information about the different grades,
 see @ref{Compilation model options}.)
 
-Enabling profiling has several effects.
+Enabling @samp{mprof} or @samp{mdprof} profiling has several effects.
 First, it causes the compiler to generate slightly modified code,
 which counts the number of times each predicate or function is called,
 and for every call, records the caller and callee.
@@ -5669,6 +5691,13 @@ Third, if you enable graph profiling,
 the compiler will generate for each source file
 the static call graph for that file in @samp{@var{module}.prof}.
 
+Enabling @samp{threadscope} profiling causes the compiler to build the project
+against a different runtime system.
+This runtime system logs events relevant to parallel execution.
+ at samp{threadscope} support uses special x86 and x86_64 instructions to access the
+processor's time stamp counter,
+therefore, it is not supported on other architectures.
+
 @node Creating profiles
 @section Creating profiles
 @cindex Profiling
@@ -5703,6 +5732,10 @@ will use two of those files (@file{Prof.
 and a two others: @file{Prof.MemoryWords} and @file{Prof.MemoryCells}.
 Executables compiled with @samp{--deep-profiling}
 save profiling data in a single file, @file{Deep.data}.
+Executables compiled with @samp{--parallel --threadscope}
+save profiling data in a single file with the same name as the program being
+profiled and the extension @samp{.eventlog}, for example
+ at file{my_program.eventlog}.
 
 It is also possible to combine @samp{mprof} profiling results
 from multiple runs of your program.
@@ -5717,7 +5750,7 @@ when running your program with @samp{mpr
 If this happens, just run it again --- the problem occurs only very rarely.
 The same vulnerability does not occur with @samp{mdprof} profiling.
 
-With both profilers,
+With the @samp{mprof} and @samp{mdprof} profilers,
 you can control whether time profiling measures
 real (elapsed) time, user time plus system time, or user time only,
 by including the options @samp{-Tr}, @samp{-Tp}, or @samp{-Tv} respectively
@@ -6094,6 +6127,26 @@ all		map
 internal	set
 @end example
 
+ at node Using threadscope
+ at section Using threadscope
+
+ at pindex threadscope
+ at pindex show-ghc-events
+ at cindex ThreadScope profiling
+ at cindex Parallel execution profiling
+
+The ThreadScope tools are not distributed with Mercury.
+For information about how to install them please see the
+ at file{README.ThreadScope} file included in the Merucry distribution.
+
+ThreadScope provides two programs, @samp{threadscope} and @samp{show-ghc-events},
+both tools can be used to view @file{*.eventlog} profiles.
+ at samp{show-ghc-events} lists the ThreadScope events in sorted order.
+ at samp{threadscope} provides a browseable graphical display.
+Both programs accept the name of a @file{*.eventlog} file on the command
+line, the @samp{threadscope} program provides a menu from which users can
+choose a file to open.
+
 @node Profiling and shared libraries
 @section Profiling and shared libraries
 @pindex mprof
@@ -7316,7 +7369,7 @@ The set of aspects and their alternative
 @cindex .decldebug (grade modifier)
 @c @cindex .ssdebug (grade modifier)
 @cindex .par (grade modifier)
- at c @cindex .threadscope (grade modifier)
+ at cindex .threadscope (grade modifier)
 @cindex prof (grade modifier)
 @cindex memprof (grade modifier)
 @cindex profdeep (grade modifier)
@@ -7329,7 +7382,7 @@ The set of aspects and their alternative
 @cindex decldebug (grade modifier)
 @c @cindex ssdebug (grade modifier)
 @cindex par (grade modifier)
- at c @cindex threadscope (grade modifier)
+ at cindex threadscope (grade modifier)
 @table @asis
 @item What target language to use, what data representation to use, and (for C) what combination of GNU C extensions to use:
 @samp{none}, @samp{reg}, @samp{jump}, @samp{asm_jump},
@@ -7362,10 +7415,10 @@ small segments: @samp{stseg} (the defaul
 @item Whether to use a thread-safe version of the runtime environment:
 @samp{par} (the default is a non-thread-safe environment).
 
- at c @item Whether to include support for profile the execution of parallel
- at c programs:
- at c @samp{threadscope} (the default is no support for profiling parallel
- at c execution).
+ at item Whether to include support for profile the execution of parallel
+programs:
+ at samp{threadscope} (the default is no support for profiling parallel
+execution).
 @c See also the @samp{--profile-parallel-execution} runtime option.
 
 @end table
@@ -7499,6 +7552,12 @@ and grade modifier; they are followed by
 @c @item @samp{.ssdebug}
 @c @code{--ss-debug}.
 
+ at item @samp{.par}
+ at code{--parallel}.
+
+ at item @samp{.par.threadscope}
+ at code{--parallel --threadscope}.
+
 @end table
 
 @end table
@@ -7860,6 +7919,31 @@ or for backtrackable destructive update.
 This option is only supported by the C back-ends.
 
 @sp 1
+ at item @code{--parallel}
+ at findex --parallel
+ at cindex Parallel evaluation
+Enable support for parallel evaluation.
+This enables runtime and code generation options necessary for taking
+advantage of a shared memory parallel computer.
+Parallel evaluation can be achieved by using either the parallel conjunction
+operator or the concurrency support provided in the @samp{thread} module of the
+standard library.
+ at xref{Goals, parallel conjunction, Goals, mercury_ref, The Mercury
+Language Reference Manual}, and
+ at xref{thread, the thread module, thread, mercury_library, The Mercury
+Library Reference Manual}.
+This option is only supported by the C back-ends,
+note that the Java backend supports parallel evaluation without requiring this option.
+
+ at sp 1
+ at item @code{--threadscope}
+ at findex --threadscope
+ at cindex Threadscope profiling
+Enable support for threadscope profiling.
+This enables runtime support for profiling the parallel evaluation of
+programs, @xref{Using threadscope}.
+
+ at sp 1
 @item @code{--maybe-thread-safe @{yes, no@}}
 @findex --maybe-thread-safe
 Specify how to treat the @samp{maybe_thread_safe} foreign code
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 489 bytes
Desc: Digital signature
URL: <http://lists.mercurylang.org/archives/reviews/attachments/20100318/f7469d83/attachment.sig>