[m-rev.] document Java foreign language interface

[Fergus Henderson]

On 04-Dec-2003, Ralph Becket <rafe at cs.mu.OZ.AU> wrote:
> Fergus Henderson, Wednesday,  3 December 2003:
> > On 03-Dec-2003, Ralph Becket <rafe at cs.mu.OZ.AU> wrote:
> > > I think the last two paragraphs could be made clearer.  How about
> > > this:
> > > 
> > >    The arguments to the Java function will be precisely the input
> > >    arguments of the corresponding Mercury procedure (in the same order).
> > >    (If the Mercury procedure is a function with an input mode result,
> > >    then this will be the last argument to the Java function.)
> > 
> > I'm happy to consider suggestions for better wording.
> > But I don't like the specific wording that you have proposed.
> > 
> > In the Mercury language reference manual, the term "arguments"
> > does NOT include function results. [...]
>
> Point taken.  How about s/input arguments/inputs/?

OK.

> > >    The result of the Java function will be a vector comprised of the
> > >    output arguments of the Mercury procedure (in the same order).
> > >    (If the Mercury procedure can fail then the last item in the vector
> > >    will be a @samp{boolean} success indicator, with a @samp{true} value
> > >    denoting success and a @samp{false} value denoting failure.)
> > 
> > Again, that wording does not seem appropriate, because
> > in the Mercury language reference manual, the term "arguments"
> > does not include function results.
> 
> s/output arguments/outputs/?

Hmm.  I don't know whether it is reasonable to consider the success
indicator as one of the outputs, and even if you do, it certainly
doesn't have a natural ordering with regard to the rest of them,
so the part "in the same order" is a bit odd.  The parenthetical
sentence seems to be doing more work than is appropriate for something
in parentheses ;-)

More seriously, I just realized that my original documentation was wrong:
the success indicator goes at the start of the sequence, not at the end.

How about this:

    The result of the Java function will be a sequence comprised of
    the outputs of the Mercury procedure.  If the Mercury procedure's
    determinism indicates that it can fail, then its first output will
    be a @samp{boolean} success indicator, with a @samp{true} value
    denoting success and a @samp{false} value denoting failure. The
    remaining outputs will be the subsequence of the Mercury procedure's
    arguments and function result (if any) that have output modes.

> > > Does this apply to nested values of type MercuryTypeName or just
> > > top-level arguments?
> > 
> > It applies to nested values, but generally they won't show up in the
> > Java interface.  The exception is arrays, where e.g. a Mercury type
> > `array(foo)' will map to a Java type `Foo[]' if the Mercury type
> > `foo' is a declared as a Java foreign_type for `Foo'.
> > 
> > I'm not sure if this needs any explicit wording to make this clear,
> > or what form such wording would take; suggestions welcome.
> 
> Hmmm... what's the mapping from data constructors to Java classes?  Or
> is this private, in the sense that the programmer has to export field
> accessor predicates to Java if they want to manipulate Mercury values
> from within Java?

I'm happy to keep it private for now, and document it only in the source
code (mlds.m, ml_type_gen.m and/or mlds_to_java.m) not in the language
reference manual.  Currently the actual mapping is a bit too likely to
change to document for users, IMHO.

Note that "pragma export" is not yet part of the language-independent
foreign language interface chapter, and is not yet supported for Java.

> Also, is there any harm in letting the programmer treat arrays as
> though they we Objects?

Yes -- converting Java arrays to Mercury or vice versa would be much
more complicated and also costly (since it would require making copies).

> > Like this?
> > 
> > 	With our current implementation, the Java code must set the
> > 	values even if the procedure fails setting @samp{succeeded} to
> > 	@code{false}.
> > 
> > That doesn't parse properly. 
> 
> It doesn't?  How about
> 
> 	With our current implementation, the Java code must set the
> 	values even if the procedure fails (i.e. sets @samp{succeeded} to
> 	@code{false}.)

OK.

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "I have always known that the pursuit
The University of Melbourne         |  of excellence is a lethal habit"
WWW: <http://www.cs.mu.oz.au/~fjh>  |     -- the last words of T. S. Garp.
--------------------------------------------------------------------------
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
--------------------------------------------------------------------------