[m-rev.] document Java foreign language interface
Fergus Henderson
fjh at cs.mu.OZ.AU
Fri Dec 5 16:14:09 AEDT 2003
On 03-Dec-2003, Fergus Henderson <fjh at cs.mu.OZ.AU> wrote:
> 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
> > > 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.
On second thoughts, I changed my mind. The proposed wording mixes
rules and rationale. A language specification ought to do its best
to clearly separate those.
But your suggestion to break it up into two sentences is a good one.
I've changed it to the following:
Arguments of type @samp{io__state} or @samp{store__store(_)}
are not passed at all. (The reason for that is that these types
represent mutable state, and in IL modifications to mutable
state are done via side effects, rather than argument passing.)
> > > +Java code for procedures whose determinism indicates that they cannot fail
> > > +should not access the @code{succeeded} variable.
> >
> > s/access/make reference to/
>
> OK.
On second thoughts, I decided to go with "refer to"
rather than "make reference to".
> > > +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
> + at 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.
On second thoughts, I'll go with the first three changes
s/Java code/The Java code/
s/any procedure/a procedure/
s/could fail/can fail/
but I'll stick with "a value of type @samp{boolean}" rather
than "either @code{true} or @code{false}", since the latter
could easily be misinterpreted as disallowing the use of
boolean expressions which are not literals.
Relative diff follows.
--- reference_manual.texi.bak2 2003-12-05 15:20:44.000000000 +1100
+++ reference_manual.texi 2003-12-05 16:12:37.000000000 +1100
@@ -1635,7 +1635,7 @@
These labels cause the compiler to generate functions which can
be used to conveniently select and update fields of a term
in a manner independent of the definition of the type
-(@pxref{Field access functions}). A labelled argument is of the
+(@pxref{Field access functions}). A labelled argument has the
form @w{@code{@var{fieldname} :: @var{Type}}}. It is an error for
two fields in the same module to have the same label.
@@ -4645,7 +4645,7 @@
function's type signature. This constrains the values that can be taken
by type variables in the signature to belong to particular type classes.
-A type class constraint is of the form:
+A type class constraint has the form:
@example
<= @var{Typeclass}(@var{Type}, @dots{}), @dots{}
@@ -5633,10 +5633,10 @@
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 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.
+passed or returned at all.
+(The reason for this is that these types represent mutable state,
+and in IL modifications to mutable state are done via side effects,
+rather than argument passing.)
@node Java data passing conventions
@subsection Java data passing conventions
@@ -5676,26 +5676,26 @@
appended to the list of input parameters, so that the Mercury function
result becomes the last parameter to the corresponding Java function.
-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
- 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.
-
+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.
+
+If the sequence has length zero then the return type of the
+Java function is @samp{void}.
+If the sequence has length one then the return type of the
+Java function is the type of the item in question.
+Otherwise, the Java function will return an array of type
+ at samp{java.lang.Object[]}.
+
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.
+passed or returned at all.
+(The reason for this is that these types represent mutable state,
+and in Java modifications to mutable state are done via side effects,
+rather than argument passing.)
@c -----------------------------------------------------------------------
@@ -5910,7 +5910,7 @@
to the same label being defined twice inside a single C function.
C code in a @code{pragma foreign_proc} declaration
-for any procedure whose determinism indicates that it could fail
+for any procedure whose determinism indicates that it can fail
must assign a truth value to the macro @samp{SUCCESS_INDICATOR}.
For example:
@@ -6016,7 +6016,7 @@
@node Using pragma foreign_type for C
@subsubsection Using pragma foreign_type for C
-The C @samp{pragma foreign_type} declaration is of the form:
+A C @samp{pragma foreign_type} declaration has the form:
@example
:- pragma foreign_type("C", @var{MercuryTypeName}, @var{CForeignType}).
@@ -6031,8 +6031,8 @@
@samp{void (*)(void)}. However, it would be OK to use a typedef name
which was defined as a function pointer type.)
-With @samp{--gc accurate}, foreign_types which are C pointer types
-must not point to the Mercury heap.
+ at strong{With @samp{--gc accurate}, foreign_types which are C pointer types
+must not point to the Mercury heap.}
If the @var{MercuryTypeName} is the type of a parameter of a procedure
defined using @samp{pragma foreign_proc},
@@ -6085,7 +6085,7 @@
@ref{IL and C# data passing conventions}.
C# code in a @code{pragma foreign_proc} declaration
-for any procedure whose determinism indicates that it could fail
+for any procedure whose determinism indicates that it can fail
must assign a value of type @samp{bool} to the variable
@samp{SUCCESS_INDICATOR}. For example:
@@ -6176,7 +6176,7 @@
@node Using pragma foreign_type for IL
@subsubsection Using pragma foreign_type for IL
-The IL @samp{pragma foreign_type} declaration is of the form:
+The IL @samp{pragma foreign_type} declaration has the form:
@example
:- pragma foreign_type("IL", @var{MercuryTypeName}, @var{DotNetForeignType}).
@@ -6256,13 +6256,13 @@
").
@end example
-IL code for procedures whose determinism indicates they could fail
+IL code for procedures whose determinism indicates they can fail
is currently not supported.
@c XXX document how semidet works -- but get it working first.
@c
@c The IL code in a @code{pragma foreign_proc} declaration
- at c for any procedure whose determinism indicates that it could fail
+ at c for any procedure whose determinism indicates that it can fail
@c must assign a truth value to the local variable @samp{SUCCESS_INDICATOR}.
@c For example:
@c
@@ -6313,7 +6313,7 @@
@node Using pragma foreign_type for Java
@subsubsection Using pragma foreign_type for Java
-The Java @samp{pragma foreign_type} declaration is of the form:
+A Java @samp{pragma foreign_type} declaration has the form:
@example
:- pragma foreign_type("Java", @var{MercuryTypeName}, @var{JavaType}).
@@ -6321,10 +6321,9 @@
The @var{JavaType} can be any accessible Java type.
-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}.
+The effect of this declaration is that Mercury values of type
+ at var{MercuryTypeName} will be passed to and from Java foreign_procs
+as having type @var{JavaType}.
@c XXX `pragma export' not supported yet for Java
@c Furthermore, any Mercury procedure exported with @samp{pragma export}
@@ -6346,10 +6345,10 @@
for mapping Mercury types to Java types are described in
@ref{Java data passing conventions}.
-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}.
-For example:
+The Java code in a @code{pragma foreign_proc} declaration
+for a procedure whose determinism indicates that it can fail
+must assign a value of type @samp{boolean} to the variable
+ at samp{succeeded}. For example:
@example
:- pred string__contains_char(string, character).
@@ -6363,13 +6362,13 @@
@noindent
Java code for procedures whose determinism indicates that they cannot fail
-should not access the @code{succeeded} variable.
+should not refer to the @code{succeeded} variable.
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.e. the Java code sets the @samp{succeeded} variable to @code{false}).
+(i.e. sets the @samp{succeeded} variable to @code{false}).
@c If the procedure
@c succeeds, the Java code must set the values of all output arguments
@c If the procedure fails, the Java code need only
@@ -6474,7 +6473,7 @@
and the rules relating IL types to MC++ types.
MC++ code in a @code{pragma foreign_proc} declaration
-for any procedure whose determinism indicates that it could fail
+for any procedure whose determinism indicates that it can fail
must assign a value of type @samp{bool} to the variable
@samp{SUCCESS_INDICATOR}. For example:
@@ -6718,7 +6717,7 @@
then the behaviour is undefined --- your program may misbehave or crash.)
The C code in a @code{pragma c_code} declaration
-for any procedure whose determinism indicates that it could fail
+for any procedure whose determinism indicates that it can fail
must assign a truth value to the macro @samp{SUCCESS_INDICATOR}.
For example:
@@ -7078,9 +7077,9 @@
function will 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; that's because these types represent mutable state,
-and in C modifications to mutable state are done via side effects,
-rather than argument passing.
+are not passed at all. (The reason for this is that these types
+represent mutable state, and in C modifications to mutable state
+are done via side effects, rather than argument passing.)
Calling polymorphically typed Mercury procedures from C is a little bit
more difficult than calling ordinary (monomorphically typed) Mercury procedures.
@@ -7190,10 +7189,10 @@
then the C 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;
-that's because these types represent mutable state,
+passed at all.
+(The reason for this is that these types represent mutable state,
and in C modifications to mutable state are done via side effects,
-rather than argument passing.
+rather than argument passing.)
@c XXX foreign type should be documented here.
--
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
--------------------------------------------------------------------------
More information about the reviews
mailing list