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

[Julien Fischer]

On Thu, 18 Mar 2010, Paul Bone wrote:

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

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.

> +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

There is an extraneous "i" at the end of that line.

I suggest:

    threadscope depends upon the following Haskell libraries:

      etc etc

    Many of these are provided ...

> +
> +    array
> +    binary
> +    cairo
> +    containers
> +    filepath
> +    ghc-events
> +    glade
> +    gtk
> +    mtl
> +
> +Note that the cairo, gtk and glade modules are provided by the gtk2hs package.

I suggest removing those three from the list and just listing gtk2hs
then.

> +
> +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.",

At various points throughout this diff, you refer to it as either
parallel execution or parallel evaulation.  Pick one and stick to it.

> +        "\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.)

> 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

s/a compilation error/an error/

> +determinism other than @samp{det} or @samp{cc_multi}.
> + at xref{Determinism categories}.

...


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

...

> @@ -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},

    ... the @samp{--parallel} and @samp{--threadscope} options ...

> + 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

s/project/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 +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}

s/@samp{--parallel --threadscope}/@samp{--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}.

I suggest:

   Executables compiled with the @sample{--threadscope}
   write profiling data to a file whose name is that of the
   program being profiled with the extension @samp{.eventlog}.
   For example, the profile for the program @samp{my_program} would
   be written to the file @file{my_program.eventlog}.

(In the longer term, you should consider adding options to the runtime
that allow some control over what the name of the profile file is,
similar to what is done for the trace counts mechanism.)

...

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

s/Merucry/Mercury/

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

I suggest:

    ThreadScope provides two programs that can be used to view
    profiles in @file{.eventlog} files.  The first,
    @samp{show-ghc-events}, lists the ThreadScope events in sorted
    order, while the second, @samp{threadscope} provides a
    graphical display for browsing the profile.

(Also, what does "sorted order" mean here?  Sorted by what?)

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

Make that last sentance into two sentances.

...

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

s/profile/profiling/

> +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}.
> +

This is a list of grade components; .par.threadscope is two
grade components., so this should just be:

    @item @samp{.threadscope}
    @code{--threadscope}

(The fact that --threadscope also requires --parallel is not
important here, and is mentioned elsewhere anyway.)

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

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

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

Julien.
--------------------------------------------------------------------------
mercury-reviews mailing list
Post messages to:       mercury-reviews at csse.unimelb.edu.au
Administrative Queries: owner-mercury-reviews at csse.unimelb.edu.au
Subscriptions:          mercury-reviews-request at csse.unimelb.edu.au
--------------------------------------------------------------------------