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

[Paul Bone]

On Mon, Mar 22, 2010 at 04:19:05PM +1100, Julien Fischer wrote:
> 
> Hi Paul,
> 
> On Mon, 22 Mar 2010, Paul Bone wrote:
> 
> > On Sun, Mar 21, 2010 at 05:52:23AM +1100, Julien Fischer wrote:
> 
> > > > 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
> > > > @@ -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
> > >
> > > s/programms/programs/
> 
> 
> Did you fix this one?  (It is helpful if you indicate that you have
> addressed each review comment in your response.)

Yep.

Everything that I didn't comment on I changed according to your suggestion.

> ...
> 
> > This section now reads:
> >
> >     @sp 1
> >     @item @code{--parallel}
> >     @findex --parallel
> >     @cindex Parallel execution
> >     In low-level C grades this enables support for parallel execution.
> >     Parallel execution can be achieved by using either the parallel conjunction
> >     operator or the concurrency support provided in the @samp{thread} module of the
> 
> Delete the word "provided".

Yep.

> >     standard library.
> >     @xref{Goals, parallel conjunction, Goals, mercury_ref, The Mercury
> >     Language Reference Manual}, and
> >     @xref{thread, the thread module, thread, mercury_library, The Mercury
> >     Library Reference Manual}.
> >
> >     In high-level C grades this enables support for concurrency, which is
> >     accessible via the @samp{thread} module in the standard library.
> >     The runtime uses POSIX threads to achieve this, therefore it also supports
> >     parallel execution.
> >
> >     The other grades, (Java, IL and Erlang) support concurrency without this
> >     option.
> 
> I suggest:
> 
>       The Java, IL and Erlang grades support concurrency without this option.
> 

Yep.

> 
> Could you please post a revised diff once you have addressed the above.


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	22 Mar 2010 03:57:09 -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 some 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 for the low-level C grade.",
+        "\tEnable concurrency (via pthreads) for the high-level C grade.",
         "--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	22 Mar 2010 03:57:10 -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 an 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	22 Mar 2010 06:08:38 -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,35 @@ 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 programs can be analyzed with a third
+profiler called @samp{threadscope}.
+ at samp{threadscope} allows programmers to visualise CPU utilisation for work,
+garbage collection, and idle time.
+This enables programmers to see the effect of parallelization decisions such as
+task granularity.
+The @samp{threadscope} tool is not included with the Melbourne Mercury
+Compiler,
+See @url{http://research.microsoft.com/en-us/projects/threadscope/, 
+Threadscope: Performance 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 +5665,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} and @samp{--threadscope} options to @samp{mmc},
+ at samp{mgnuc} and @samp{ml}.
 @end itemize
 
 If you are using Mmake,
@@ -5655,7 +5678,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 +5692,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 program 
+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 +5733,11 @@ 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 the @samp{--threadscope} write profiling data to a
+file whose name is that of the program being profiled with the extension
+ at samp{.eventlog}.
+For example, the profile for the program @samp{my_program} would be written to
+the file @file{my_program.eventlog}.
 
 It is also possible to combine @samp{mprof} profiling results
 from multiple runs of your program.
@@ -5717,7 +5752,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 +6129,30 @@ 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 Mercury distribution.
+
+ThreadScope provides two programs that can be used to view profiles in
+ at file{.eventlog} files.
+The first, @samp{show-ghc-events}, lists the ThreadScope events sorted from the
+earliest to the latest,
+while the second, @samp{threadscope} provides graphical display for browsing
+the profile.
+
+Both programs accept the name of a @file{.eventlog} file on the command
+line.  
+The @samp{threadscope} program also 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 +7375,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 +7388,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 +7421,8 @@ 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 profiling of parallel programs:
+ at samp{threadscope} (the default is no support for profiling parallel programs).
 @c See also the @samp{--profile-parallel-execution} runtime option.
 
 @end table
@@ -7499,6 +7556,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{.threadscope}
+ at code{--threadscope}.
+
 @end table
 
 @end table
@@ -7860,6 +7923,35 @@ 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 execution 
+In low-level C grades this enables support for parallel execution.
+Parallel execution can be achieved by using either the parallel conjunction
+operator or the concurrency support 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}.
+
+In high-level C grades this enables support for concurrency, which is
+accessible via the @samp{thread} module in the standard library.
+The runtime uses POSIX threads to achieve this, therefore it also supports
+parallel execution. 
+
+The Java, IL and Erlang grades support concurrency without this option.
+Parallel execution may also be available depending on the target's runtime. 
+
+ 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 execution 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/20100322/021432be/attachment.sig>