[m-rev.] for post-commit review: explain grades more deeply

[Julien Fischer]

Hi Zoltan,

Do you want me to commit these changes?

Julien.

On Fri, 1 May 2020, Julien Fischer wrote:

>
> On Fri, 1 May 2020, Zoltan Somogyi wrote:
>
>>  This started out as clarification of .spf, but snowballed from there.
>>
>>  For post-commit review (in the form of changes to the file) by anyone.
>>  I am particularly seeking feedback about the description of the grade
>>  modifiers dealing with threads.
>
> See the diff below.
>
>>  Two related issues. First, having the description of the whole grade
>>  system
>>  be inside the item for the --grade option in a table of options seems
>>  wrong.
>>  I would prefer if we had a whole subsubsection for it, where 9.8.0 would
>>  be
>>  if 0 was a possible subsubsection number. Opinions?
>
> I agree, the description of the grade system should be in its own
> section.  Given the level of confusion that they seem to cause, maybe
> it should be its own chapter instead?
>
> diff --git a/doc/user_guide.texi b/doc/user_guide.texi
> index 288fabd..ea19b4a 100644
> --- a/doc/user_guide.texi
> +++ b/doc/user_guide.texi
> @@  -7933,9 +7933,9 @@ and each following element (if any) is a @samp{grade 
> @@  modifier}.
>
>  The base grade specifies
>  what target language to compile the Mercury program to,
> -and if that the compiler can do this in several different ways,
> +and if the compiler can do this in several different ways,
> selects one of those ways.
> -The available base grades are the following.
> +The available base grades are:
>
> @ c What target language to use (C, C#, Java or Erlang),
> @ c for C, whether to generate idiomatic C or assembly-like code,
> @@  -7954,11 +7954,11 @@ The available base grades are the following.
>
> @ item @samp{hlc}
> This base grade calls for generating idiomatic C,
> -which we call high level C.
> +which we call high-level C.
>
> @ item @samp{none}, @samp{reg}, and @samp{asm_fast}
> These base grades calls for generating assembly-like C code,
> -which we call low level C.
> +which we call low-level C.
> @ samp{none} calls for generating standard C without using any GNU C 
> @ extensions.
> @ samp{reg} and @samp{asm_fast} both call for
>  the use of GNU C's extension for storing global variables in registers,
> @@  -7966,7 +7966,7 @@ while @samp{asm_fast} also calls for the use of two 
> @@  GNU C extensions
>  that together allow direct gotos to labels in other functions,
>  even in other modules.
>  In general, the more GNU C extensions are used,
> -the faster the programmer will be,
> +the faster the program will be,
>  but some platforms, compilers or compiler versions
>  do not support specific extensions.
>
> @@  -7985,7 +7985,6 @@ The default base grade is system dependent,
>  but will be either @samp{hlc} or @samp{asm_fast},
>  as these are the two fastest.
>
> - at c @cindex hl (compilation grade)
> @ c @cindex asm_jump (compilation grade)
> @ c @cindex fast (compilation grade)
> @ c @cindex jump (compilation grade)
> @@  -8019,7 +8018,7 @@ and not all grade modifiers are compatible with each 
> @@  other.
> @ item garbage collection
>  The default is no garbage collection beyond what the target language
>  provides.
>  C#, Java and Erlang have their own builtin garbage collectors, but C does
>  not.
> -Since gc is essential for all programs
> +Since garbage collection is essential for all programs
>  other than those with @emph{very} short runtimes,
>  base grades that target C
>  are usually followed by the @samp{.gc} grade modifier, which calls for
> @@  -8040,24 +8039,21 @@ Applications that need trailing should specify the 
> @@  grade modifier @samp{.tr}.
> @ samp{.trseg} is currently accepted as synonym for @samp{.tr}.
>
> @ item floating point precision
> -By default, the Mercury @samp{float} is implemented as
> -a double-precision floating point number,
> -which occupies 64 bits of space on virtually all platforms.
> -On platforms whose word size is 32 bits,
> -users whose programmers do not require double precision
> -may improve memory consumption and therefore speed by specifying
> -the grade modifier @samp{.spf} (short for single-precision float),
> -which calls for implementing all Mercury floats
> -as single-precision, 32 bit floating point numbers.
> -Note that on 64 bit platforms,
> -using single-precision floats
> -definitely will @emph{not} improve memory consumption,
> -and probably will not improve speed.
> -On the other hand, it may simplify the use of C APIs
> -that exclusively use single precision floats.
> +By default when targeting C, the Mercury @samp{float} type is implemented as 
> an
> +IEEE 754 double-precision floating point number, which occupies 64 bits of
> +space.
> +On platforms whose word size is 32 bits, users whose programs do not require
> +double precision may improve memory consumption and speed by specifying the
> +grade modifier @samp{.spf} (short for single-precision float), which calls 
> for
> +implementing all Mercury floats as IEEE 754 single-precision floating point
> +numbers.
> +Note that on 64 bit platforms, using single-precision floats definitely will
> + at emph{not} improve memory consumption, and will probably not improve speed.
> +On the other hand, it may simplify the use of C APIs that exclusively use
> +single precision floats.
>
> @ item stack size
> -When generating assembly-like C code,
> +When generating low-level C,
>  Mercury implements its own stacks (two of them).
>  The default is to make each stack a fixed size
>  (usually a relatively large size,
> @@  -8076,37 +8072,37 @@ small memory segments chained together in a list.
>  When there is no room in the current segment for a new stack frame,
>  we simply allocate a new segment and add it to the list.
>  This approach has higher overhead,
> -since calls to and returns from procedures we must execute more code,
> +since calls to, and returns from, procedures must execute more code,
>  but it avoids imposing any limit on stack size
>  other than the size of available memory.
>
> @ item debugging
> The default is to generate executables that do not support debugging.
> -However, when generating low level C code,
> +However, when generating low-level C code,
>  specifying one of the grade modifiers @samp{.debug} and @samp{.decldebug}
>  will cause the compiler to generate executables
>  that can be debugged using the Mercury debugger @samp{mdb}.
>  The difference between them is that
>  the declarative debugging aspects of @samp{mdb}
>  will work only with @samp{.decldebug}.
> -The price of this is that @samp{.decldebug} will result
> +The price of this is that @samp{.decldebug} results
>  in significantly larger executable files.
> @ c @samp{.ssdebug}
>
> @ item threads
> -The default is whatever thread support is given by the target language.
> +The default is whatever thread support is provided by the target language.
> When targeting C,
> -thread support can be enabled by specifying the grade modifier @samp{.par}.
> -When targeting low level C,
> +thread support must be enabled by specifying the grade modifier @samp{.par}.
> +When targeting low-level C,
>  this also enables the use of the parallel conjunction operator @samp{&}.
>  Since Mercury implements parallel conjunctions
> -only in low level C grades with the @samp{.par} grade modifier,
> +only in low-level C grades with the @samp{.par} grade modifier,
>  in every other situation, the compiler silently converts
>  every occurrence of @samp{&} to a comma,
>  the usual @emph{sequential} conjunctions operator.
>
> @ item thread profiling
> -In low level C grades with the grade modifier @samp{.par},
> +In low-level C grades with the grade modifier @samp{.par},
>  users can enable support for ThreadScope-style thread profiling
>  by also specifying the grade module @samp{.threadscope}.
>  The default is no support for profiling.
> @@  -8114,7 +8110,7 @@ Note that support for this form of profiling is 
> @@  experimental.
>
> @ item minimal model tabling
> The default is no support for minimal model evaluation.
> -When targeting low level C, users can specify the grade modifier @samp{.mm},
> +When targeting low-level C, users can specify the grade modifier @samp{.mm},
>  which enables support for minimal model tabled evaluation of procedures.
>
> @ end table
> @@  -10643,7 +10639,7 @@ grade.
> @ c @findex --profile-parallel-execution
> @ c Tells the runtime to collect and write out parallel execution profiling
> @ c information to a file named @file{parallel_execution_profile.txt}.
> - at c This only has an effect if the executable was built in a low level c,
> + at c This only has an effect if the executable was built in a low-level C,
> @ c parallel, threadscope grade.
> @ c
> @ c @sp 1
>
> Julien.
>
>