[m-rev.] for review: il as a foreign language

[Tyson Dowd]

On 17-Jul-2001, Fergus Henderson <fjh at cs.mu.OZ.AU> wrote:
> > + at example
> > +:- pragma foreign_proc("@var{Lang}", @var{Pred}(@var{Var1}::@var{Mode1}, @var{Var2}::@var{Mode2}, @dots{}),
> > +        @var{Attributes}, @var{Foreign_Code}).
> > + at end example
> 
> I think the syntax there should be changed from "Lang" to 'Lang'.
> The set of supported languages is an enumeration, not an arbitrary
> string literal, so we should use enumeration-like syntax rather than
> string literal syntax.

I'd prefer to document what is implemented.
If you want to change the syntax we can have a different discussion
about that. 

AFAI remember you suggested using strings in the first place (I was
going to use 'c' and 'mcplusplus' to begin with), so I'm not keen to go
and change it lightly.  Every file in the library has to be updated to
use the new syntax if you change it, and there are already a bunch of
changes that are being bootstrapped in the syntax.

> > + at noindent
> > +or
> > +
> > + at example
> > +:- pragma foreign_proc("@var{Lang}", @var{Func}(@var{Var1}::@var{Mode1}, @var{Var2}::@var{Mode2}, @dots{}) = (@var{Var}::@var{Mode}),
> > +        @var{Attributes}, @var{Foreign_Code}).
> > + at end example
> > +
> > + at noindent
> > +means that any calls to the specified mode of @var{Pred} or @var{Func}
> > +will result in execution of the foreign code given in @var{Foreign_Code}
> > +written in language @var{Lang}.
> 
> That isn't true.  E.g. the "MC++" foreign procs in the std library
> have no effect when compiling to C.
> 
> > +Additional restrictions on the foreign language interface code
> > +depend on the foreign language, the backend target, and the implementation.
> 
> Different restrictions for different foreign languages are fine, but
> implementations shouldn't be allowed to add arbitrary restrictions here.
> If they are, then it would be impossible to write code that is portable
> between different implementations.  That would be a bad thing.
> 
> Now, it may be unavoidable, but I'd like to see a detailed rationale
> before including that in the language reference manual.

Since the implementation doesn't add arbitry restrictions, I will just
remove "the implementation".

> Also, I don't think the readers of the Mercury language reference manual will
> know what you mean by "the backend target" here.  You'd need a more detailed
> description.  It may be best to just leave that out; it's subsumed by
> "the implementation".

Hmm... now I have to leave the "the implementation" here!

I will instead simply say "compilation options".

> 
> (And by the way, if the word "backend" should remain, s/backend/back-end/.
> I think the rule with these kinds of things is that
> "backend" is a noun, "back-end" is an adjective.)

It's true, another arbitrary english rule...
> 
> > + at item @samp{Managed C++}
> > +Use the string "MC++" to set the foreign language to Managed C++.
> > +Default foreign language on all backends which compile to IL.
> > +Only available on backends that compile to IL.
> 
> Many readers won't know what "Managed C++" is, so you should explain,
> e.g. "(also known as Microsoft C++ with managed extensions)".
> 
> s/Only available/In the current implementation, this is only available/
> But again, I think the documentation about these implementation-specific
> restrictions on which languages can be used for which back-end should
> go in the user guide.
> 
> > +Requires a Managed Extensions for C++ compiler installed.
> 
> The analagous requirement is true for every foreign language.
> It should be documented in the language-independent part of the
> documentation.




> 
> > + at item @samp{C#}
> > +Use the string "C#" to set the foreign language to C#.
> > +Only available on backends that compile to IL.
> > +Requires a C# compiler installed.
> > +To use the pass mmc @samp{--use-foreign-language csharp} and
> > + at samp{--backend-foreign-language csharp}.
> 
> "To use the pass" is not grammatically correct.
> 
> > + at item @samp{IL}
> > +Use the string "IL" to set the foreign language to IL.
> 
> Many readers won't know what "IL" is, so you should explain further.
> 
> > + at node Interfacing with C#
> > + at subsection Interfacing with C#
> > +
> > +Currently undocumented, sorry.
> > +
> > + at node Interfacing with Managed C++
> > + at subsection Interfacing with Managed C++
> > +
> > +Currently undocumented, sorry.
> 
> You should add "@c XXX" to those two places.
> 
> > + at node Interfacing with IL
> > + at subsection Interfacing with IL
> > +
> > +Variables can be accessed from IL by using ldloc (for input) 
> > +stloc (for output).
> 
> s/stloc/and stloc/
> s/for input/for input parameters/
> s/for output/for output parameters/
> 
> > Do not use a ret instruction or tail.call
> > instruction within the handwritten IL code.
> 
> So "tail.calli" is OK then? ;-)
> 
> You need to generalize this.
> 
> > +The IL code in a @code{pragma foreign_proc} declaration
> > +for any procedure whose determinism indicates that it could fail
> > +must assign a truth value to the local variable @samp{succeeded}.
> > +For example:
> > +
> > + at example
> > +:- pred same(int::in, int::in) is semidet.
> > +:- pragma foreign_proc("il", same(X::in, Y::in), [max_stack_size(2)], "
> > +	ldloc X
> > +	ldloc Y
> > +	ceq
> > +	stloc succeeded
> > +").
> > + at end example
> 
> This is a bad design, IMHO.  It would be much better for the semidet
> IL code to leave the truth value on the IL stack, and have the compiler
> automatically generate the "stloc succeeded" instruction.
> 
> Apart from anything else, this would make it easier for peephole optimization
> to optimize away the "stloc succeeded", "ldloc succeeded" pairs.
> It's also nicer because it avoids hard-coding the magic name "succeeded".

Ok, this is nicer, I can add it to the wishlist, if it is easy to
implement I can do it reasonably soon.  I can start a list of
things that need to be fixed before the documentation/syntax is pronounced
"stable".
 
> Incidentally, it's generally a good idea to write the documentation and get it
> reviewed before writing the code, because these kind of design issues often
> come up when the documentation is reviewed.

Hey, I have enough trouble with creeping featuritis when I just post code
diffs!  *Anyone* can comment on documentation (and they often do)!

-- 
       Tyson Dowd           # 
                            #  Surreal humour isn't everyone's cup of fur.
     trd at cs.mu.oz.au        # 
http://www.cs.mu.oz.au/~trd #
--------------------------------------------------------------------------
mercury-reviews mailing list
post:  mercury-reviews at cs.mu.oz.au
administrative address: owner-mercury-reviews at cs.mu.oz.au
unsubscribe: Address: mercury-reviews-request at cs.mu.oz.au Message: unsubscribe
subscribe:   Address: mercury-reviews-request at cs.mu.oz.au Message: subscribe
--------------------------------------------------------------------------