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

[Julien Fischer]

On Mon, 22 Mar 2010, Paul Bone wrote:

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

s/in the/by the/

> +        "\tgrades on some x86 and x86_64 processors."

Perhaps, processors that support the relevant instructions should be
listed in README.threadscope and pointer from here to there added.

>      ]),
>
>      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.",

s/grade/grades/ in both spots.

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

I suggest:

	The order in which parallel conjuncts begin execution is
	not fixed.

> 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

...

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

Or indeed, all x86 and x86_64 processors.  Again, I think a more
specific idea of what processor a user requires should be given in
README.Threadscope and that file pointed to from here.

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

Delete "the"  (Or add the word "option" after @samp{--threadscope})

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

...

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

s/provides/provides a/

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

...

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

It may also support parallel execution of threads -- it wont't if I am
using a single core machine.

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