[m-rev.] for review: improve documentation of --fully-strict

[Ian MacLarty]

On Mon, Sep 24, 2007 at 08:27:29PM +1000, Julien Fischer wrote:
>
> On Mon, 24 Sep 2007, Ian MacLarty wrote:
>
>> On Mon, Sep 24, 2007 at 04:52:27PM +1000, Julien Fischer wrote:
>>>
>>> On Mon, 24 Sep 2007, Ian MacLarty wrote:
>>>
>>>> On Mon, Sep 24, 2007 at 03:44:40PM +1000, Julien Fischer wrote:
>>>>>
>>>>> On Mon, 24 Sep 2007, Ian MacLarty wrote:
>>>>>
>>>>>> On Mon, Sep 24, 2007 at 03:02:06PM +1000, Julien Fischer wrote:
>>>>>>>
>>>>>>> On Fri, 21 Sep 2007, Ian MacLarty wrote:
>>>>>>>
>>>>>>>> Estimated hours taken: 0.1
>>>>>>>> Branches: main
>>>>>>>>
>>>>>>>> compiler/options.m:
>>>>>>>> doc/user_guide.texi:
>>>>>>>> 	Document that --no-fully-strict also replaces det goals that 
>>>>>>>> produce
>>>>>>>> 	no outputs with `true' and goals that always fail with `fail'.
>>>>>>>
>>>>>>> simplify.m only does such replacements when when the goal is not 
>>>>>>> impure
>>>>>>> however.
>>>>>>>
>>>>>>
>>>>>> Okay, I'll mention that the goal should not be impure.
>>>>>>
>>>>>>>> 	Also change the documented option to --no-fully-strict instead
>>>>>>>> 	of --fully-strict, because --fully-strict is the default.
>>>>>>>> 	XXX Should it be the default?
>>>>>>>
>>>>>>> I think yes; it's the least surprising choice.
>>>>>>>
>>>>>>
>>>>>> The reference manual says the following:
>>>>>>
>>>>>> The University of Melbourne Mercury implementation offers eight
>>>>>> different semantics, which can be selected with different
>>>>>> combinations of the @samp{--no-reorder-conj}, 
>>>>>> @samp{--no-reorder-disj},
>>>>>> and @samp{--fully-strict} options.  (The @samp{--fully-strict} option
>>>>>> prevents the compiler from improving completeness by optimizing away
>>>>>> infinite
>>>>>> loops or calls to @code{require.error/1} or @code{exception.throw/1}.)
>>>>>> The default semantics are the commutative semantics.  Enabling all of
>>>>>> these
>>>>>> options gives you the strict sequential semantics.  Enabling just some
>>>>>> of them gives you a semantics somewhere in between.
>>>>>>
>>>>>> This seems to suggest that the default is supposed to be
>>>>>> --no-fully-strict.
>>>>>>
>>>>>> Shall I change the reference manual too then?
>>>>>
>>>>> Yes; I think all you need to do is change the sense of the 
>>>>> parenthesised
>>>>> setence that begins "The @samp{--fully-string} option ..." to "... 
>>>>> allows
>>>>> the
>>>>> compiler to improve completeness ...".
>>>>>
>>>>
>>>> Wouldn't the default semantics now be the *strict* commutative 
>>>> semantics?
>>>
>>> Isn't that what they are anyway?
>>>
>>
>> Well the reference manual currently says that the default semantics
>> are the "commutative semantics", not the "strict commutative semantics".
>
> I took that to mean the strict commutative semantics are the default 
> semantics
> since they were they ones being discussed a paragraph or so back.  (Note
> that the manual only gives names to two semantics, the strict sequential
> and the strict commutative.)
>

I took them to mean the semantics you get with --reorder-conj,
--reorder-disj and --no-fully-strict.

> In any case, the strict commutative semantics are what the implementation
> gives you by default, e.g. the default is --reorder-conj,
> --reorder-disj, and --fully-strict.
>

I know, but I don't think that's clear from the reference manual.  I
took it to mean that by default you get:

--reorder-conj, --reorder-disj, --no-fully-strict

The sentence "Enabling just some of these options gives you a semantics
somewhere in between [the strict sequencial and commutative]" is
confusing, because if you give just

--no-reorder-conj --no-reorder-disj

you get exactly the strict sequencial semantics.

>> As I understand it goals can't be deleted in the strict commutative
>> semantics, but in other commutative semantics (such as the one given by
>> --no-fully-strict) they can, as long as they are at least as complete as
>> the strict commutative semantics.
>>
>> Have I got that right?
>

No, I think it should be changed to the following:

Index: doc/reference_manual.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/reference_manual.texi,v
retrieving revision 1.408
diff -u -r1.408 reference_manual.texi
--- doc/reference_manual.texi	13 Sep 2007 03:35:05 -0000	1.408
+++ doc/reference_manual.texi	25 Sep 2007 02:14:05 -0000
@@ -6135,14 +6135,14 @@
 Programmers who care about efficiency more than portability can write
 code for these implementation-defined semantic models.  Programmers who
 care about efficiency @emph{and} portability can achieve this by writing
-code for the commutative semantics.
+code for the strict commutative semantics.
 Of course, this is not
 quite as easy as using the strict sequential semantics, since it is
 in general not sufficient to test your programs on just one
 implementation if you are to be sure that it will be able to use the
 maximally efficient operational semantics on any implementation.
 However, if you do write code which works for all possible executions
-under commutative semantics (i.e.@: for all possible orderings of
+under the strict commutative semantics (i.e.@: for all possible orderings of
 conjunctions and disjunctions), then you can be guaranteed that it
 will work correctly on every implementation, under every possible
 implementation-defined semantics.
@@ -6150,12 +6150,15 @@
 The University of Melbourne Mercury implementation offers eight
 different semantics, which can be selected with different
 combinations of the @samp{--no-reorder-conj}, @samp{--no-reorder-disj},
-and @samp{--fully-strict} options.  (The @samp{--fully-strict} option
-prevents the compiler from improving completeness by optimizing away infinite
-loops or calls to @code{require.error/1} or @code{exception.throw/1}.)
-The default semantics are the commutative semantics.  Enabling all of these
-options gives you the strict sequential semantics.  Enabling just some
-of them gives you a semantics somewhere in between.
+and @samp{--no-fully-strict} options.
+(The @samp{--no-fully-strict} option allows the compiler to improve
+completeness by optimizing away infinite loops,
+calls to @code{require.error/1} or @code{exception.throw/1}, 
+pure or semipure goals that always succeed and produce no outputs,
+or pure or semipure goals that always fail.)
+The default semantics are the strict commutative semantics.
+Enabling @samp{--no-reorder-conj} and @samp{--no-reorder-disj} gives the
+strict sequencial semantics.
 
 Future implementations of Mercury may wish to offer other operational semantics.
 For example, they may wish to provide semantics in which function

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