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

[Paul Bone]

On Mon, Mar 22, 2010 at 06:19:47PM +1100, Julien Fischer wrote:
> 
> 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/

Done.

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

I've added a section to the README.ThreadScope file that describes what
features are required along with processors that are known to work and one that
is known not to work.  I havn't listed any single-core 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.",
> 
> s/grade/grades/ in both spots.

Done.

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

Done.

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

As above.

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

Added 'option'.

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

Done.  What's wrong with my prose today!?!?

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

The same goes for the asm_fast.gc.par grade, yet we say it enables parallel
execution.  I've changed this as you've suggested but feel that it's being
pedantic.


-------------- 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/4001bb06/attachment.sig>