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

[Paul Bone]

On Sun, Mar 21, 2010 at 05:52:23AM +1100, Julien Fischer wrote:
> > 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.
> 
> What do you mean by "work" with?  Do you mean "are compiled with"?  Or
> do they require GHC 6.10 in some other way, e.g. runtime library
> dependencies.

This is now 'known to work with'.

> > 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.",
> 
> At various points throughout this diff, you refer to it as either
> parallel execution or parallel evaulation.  Pick one and stick to it.

I'm going with '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.",
> 
> That isn't true (and isn't consistent with your change to the user's
> guide below.)  The grade modifier (and option) mean something to the
> high-level C backend, i.e. enable support for concurrency in high-level
> C grades.  (See further discussion about this below.)

This is now:

        "--parallel\t\t(grade modifier: `.par')",
        "\tEnable parallel evaluation support for the low-level C grade.",
        "\tEnable concurrency (via pthreads) for the high-level C grade.",


> > 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/
> 
> > +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.
> 
> "as well as how garbage collection"  doesn't make any sense.

Rephrased:

    @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.


> > @@ -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.
> 
> The situation is (unfortunately) more complicated than that, due to
> differences between the low- and high-level C grades.  Here's
> a summary:
> 
> The --parallel option enables support for parallel execution in the
> low-level C grades.  It does not enable support for concurrency in the
> low-level C grades since *all* low-level C grades support concurrency.
> (The stuff in the thread module will work perfectly well in the non .par
> low-level C grades, although in .par grades the the threads may of
> course execute in parallel with one another.)
> 
> In the high-level C grades, --parallel, means enable support for
> concurrency.  In those grades whatever thread parallelism you get is up
> to pthreads; Mercury level parallelism is not suppored, i.e. the
> parallel conjuction operator is not supported in those grades.  (This is
> the same for the Java and IL grades, except they don't require a
> separate grade modifier / option since concurrency is always enabled for
> those -- I suspect the same is true for the Erlang grade as well.)
> 

In this way whatever parallelism you get is _always_ up to pthreads.  The stuff
in asm_fast.par is implemented in terms of pthreads.  So hlc.par style
concurrency also gives parallelism.  This is distinct from asm_fast concurrency
(without .par).

> > +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.
> 
> The last bit is not true; I can use the thread module in asm_fast.gc,
> but parallel evaluation will not be possible.
>
> > + 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.
> 
> The Java backend supports concurrency without requiring this option (as
> opposed to the high-level C grade which does require it for
> concurrency).  The Java backend does not support parallel conjunction,
> although it may execute threads in parallel depending on what the JVM
> chooses to do.
> 
> I realise the above is a bit of a mess; I think the best thing to do
> would be to describe both situations,  for example
> 
>    In low-level C grades --parallel means ...
>    In high-level C grades it means ...
>

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
    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.
    Parallel execution may also be available depending on the target's runtime. 

 
-------------- 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/30d05663/attachment.sig>