[m-rev.] document Java foreign language interface

[Fergus Henderson]

On 03-Dec-2003, Ralph Becket <rafe at cs.mu.OZ.AU> wrote:
> Fergus Henderson, Wednesday,  3 December 2003:
> > Workspace: /home/jupiter/fjh/ws-jupiter/mercury
> > Index: doc/reference_manual.texi
> > ===================================================================
> > @@ -5632,7 +5633,66 @@
> >  then the IL function should return the Mercury function result value.
> >  Otherwise the function result is appended as an extra argument.
> >  Arguments of type @samp{io__state} or @samp{store__store(_)} are not
> > -passed at all;
> > +passed or returned at all;
> > +that's because these types represent mutable state, and in IL
> > +modifications to mutable state are done via side effects,
> > +rather than argument passing.
> 
> I think the following reads better:
> 
>    Arguments of type @samp{io__state} or @samp{store__store(_)} are not
>   -passed at all;
>   +passed or returned at all
>   +because these types represent mutable state.  In IL,
>   +modifications to mutable state occur via side effects
>   +rather than argument passing.

OK.

> > +Note an extra namespace qualifier, @samp{mercury}, will be prepended to the
> > +beginning of names residing in the Mercury standard library.
> > +Mercury variables whose type is a Mercury equivalence type
> > +will be passed as the representation of the right hand side of the
> > +equivalence type.
> 
> Just out of interest, is the reason for the extra namespace qualifier
> documented somewhere?

The _fact_ of the extra namespace qualifier is documented in the comments
at the top of mlds.m, but it doesn't mention the rationale.
The rationale is that doing otherwise would lead to namespace pollution
in the target language.  I will add this to the comments in mlds.m.

> > +This mapping is subject to change and you should try to avoid writing
> > +code that relies heavily upon a particular representation of Mercury
> > +terms.
> 
> Perhaps this should be in italics?

I don't think so.  The chance of change is actually not that high,
and if change does occur, it will probably be pretty easy to modify
the application to work with the new implementation, so I don't want to
discourage people too strongly.

> > +The return values from the Java function consist of the following:
> > +first, any arguments with output modes; next, if the Mercury procedure
> > +is a function whose result has an output mode, the function result;
> > +finally, if the Mercury procedure can fail, the success indicator.
> > +The success indicator is a truth value of type
> 
> s/of type/with Java type/?

OK.

> > + at samp{boolean} indicating success or failure:
> > + at code{true} indicates success, and @code{false} indicates failure.
> > +If there are no return values, then the return type of the Java
> > +function will be @samp{void}.  If there is exactly one return
> > +value, then the Java return type will be the type of that value.
> > +If there is more than one return value, then the Java return type
> > +will be @samp{java.lang.Object[]}, and the Java function will return
> > +an array of type @samp{java.lang.Object[]} containing all the return
> > +values in the order described above.
> 
> 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.  So what you suggest above
is roughly analagous to

	All swans are white.
	(If you live in the southern hemisphere, swans' wings are black.)

;-)
In particular
	- The first sentence is not really true.
	- The second parenthetical sentence contradicts the first sentence
	- It's not immediately clear how the contraction should be resolved
	  (In the southern hemisphere, we know that the swans' wings are
	  black, but what colour is the rest of the swan?
	  If the Mercury procedure is a function with an input mode result,
	  we know that the last Java argument will be the function result,
	  but what about the other arguments?)

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

Also, the term vector is a bit too strongly suggestive of arrays.
I'd rather just use the term "sequence".

> > +Arguments of type @samp{io__state} or @samp{store__store(_)} are not
> > +passed or returned at all;
> >  that's because these types represent mutable state, and in IL
> >  modifications to mutable state are done via side effects,
> >  rather than argument passing.
> 
> As before, I think this is better:
> 
>    Arguments of type @samp{io__state} or @samp{store__store(_)} are not
>   -passed at all;
>   +passed or returned at all
>   +because these types represent mutable state.  In IL,
>   +modifications to mutable state occur via side effects
>   +rather than argument passing.

OK.

> As an aside, does capitalisation matter for the GRADE variable?

Yes, it does.

> > @@ -5965,10 +6031,8 @@
> >  @samp{void (*)(void)}.  However, it would be OK to use a typedef name
> >  which was defined as a function pointer type.)
> >  
> > - at c XXX No point documenting this until `--gc accurate'
> > - at c     is officially supported.
> > - at c With @samp{--gc accurate}, foreign_types which are C pointer types
> > - at c must not point to the Mercury heap.
> > +With @samp{--gc accurate}, foreign_types which are C pointer types
> > +must not point to the Mercury heap.
> 
> Again, I wonder whether this should be highlighted.

Yes, that one is probably worth highlighting.  Shall do.

> > + at subsubsection Using pragma foreign_type for Java
> > +
> > +The Java @samp{pragma foreign_type} declaration is of the form:
> 
> s/The/A/
> s/is of/takes/ or //has/

OK (I'll use "has").

> > +If the @var{MercuryTypeName} is the type of a parameter of a procedure
> > +defined using @samp{pragma foreign_proc},
> > +it will be passed to the foreign_proc's foreign language code
> > +as @var{JavaType}.
> 
> How about:
> 
>    The effect of this declaration is that Mercury values of type
>    @var{MercuryTypeName} will be passed to and from Java foreign_procs
>    as having type @var{JavaType}.

OK, that is much better.

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

> > + at node Using pragma foreign_proc for Java
> > + at subsubsection Using pragma foreign_proc for Java
> > +
> > +The Java code from Java pragma foreign_proc declarations will be placed in
> > +the bodies of static member functions of an automatically-generated Java class.
> > +Since such Java code will become part of a static member function,
> > +it must not refer to the @samp{this} keyword.
> > +It may however refer to static member variables or static member
> > +functions declared with @samp{pragma foreign_code}.
> 
> I take it this means the Java wrapper class also holds the foreign_code?

Not necessarily; the wrapper class might inherit from the class that
holds the foreign_code.  But in our current implementation, yes.

> > +The input and output variables for a Java @samp{pragma foreign_proc} will
> > +have Java types corresponding to their Mercury types.  The exact rules
> > +for mapping Mercury types to Java types are described in
> > + at ref{Java data passing conventions}.
> 
> How about:
> 
>    Values are passed to and from Java foreign_procs using the mapping
>    between Mercury and Java types described in @ref{Java data passing
>    conventions}.

The section on Java data passing conventions contains both the mapping
from Mercury to Java types and also an argument passing / result returning
convention; here we're only interested in the former.

If we were to say "values are passed ... using the mapping ... in @ref{...}",
then I would be worried that some readers might be mislead into thinking
that the argument passing / result returning convention applied too.

> > +Java code in a @code{pragma foreign_proc} declaration
> > +for any procedure whose determinism indicates that it could fail
> > +must assign a value of type @samp{boolean} to the variable @samp{succeeded}.
> 
> How about:
> 
>    The Java code in a @code{pragma foreign_proc} declaration for a
>    procedure whose determinism indicates it can fail must assign
>    either @code{true} or @code{false} to the variable @samp{succeeded}.

OK.

> > +For example:
> > +
> > + at example
> > +:- pred string__contains_char(string, character).
> > +:- mode string__contains_char(in, in) is semidet.
> > +
> > +:- pragma foreign_proc("Java",
> > +	string__contains_char(Str::in, Ch::in),
> > +        [will_not_call_mercury, promise_pure],
> > +        "succeeded = (Str.IndexOf(Ch) != -1);").
> > + at end example
> > +
> > + at noindent
> > +Java code for procedures whose determinism indicates that they cannot fail
> > +should not access the @code{succeeded} variable.
> 
> s/access/make reference to/

OK.

> > +
> > +Arguments whose mode is input will have their values set by the
> > +Mercury implementation on entry to the Java code.
> > +With our current implementation, the Java code must set the values
> > +of all output variables, even if the procedure fails
> 
> I'd change this
> 
> > +(i.e. the Java code sets the @samp{succeeded} variable to @code{false}).
> 
> to
> 
>    setting @samp{succeeded} to @code{false}.

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. 

If you had some punctuation in mind here, I'm not sure what it would be.

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