[m-rev.] for review: use java generics

[Peter Wang]

On 13 April 2010 02:58, Julien Fischer <juliensf at csse.unimelb.edu.au> wrote:
>>
>> -Mercury variables whose type is a type variable will be passed as
>> +Mercury variables whose types are universally quantified type variables
>> +will have generic types.
>> +Mercury variables which are existentially typed will be passed as
>
> I suggest:
>
>   Mercury variables whose types are existentially quantified type
>   variables ...

Done.

>> @@ -7009,6 +7011,9 @@ an underscore and then the type arity,
>> expressed as a decimal integer.
>> The first character of the type name will have its case inverted,
>> and the name may be mangled to satisfy Java lexical rules.
>> +Generics are used in the Java type for any type parameters.
>> +
>
> It would be worth including an example here IMO.

Done.

>> +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[]}.
>> + at c end description of --no-java-export-ref-out
>
> Is it worth documenting --no-java-export-ref-out anymore?

Probably not.

Interdiff follows.

--- gws_javageneric,20100409,a.txt	2010-04-09 15:33:14.000000000 +1000
+++ gws_javageneric,20100413,a.txt	2010-04-13 11:48:19.000000000 +1000
@@ -18,6 +18,8 @@

         Record universally quantified type variables for exported procedures.

+        Assume `--java-export-ref-out'.
+
 compiler/mlds_to_java.m:
         Output type variables in the appropriate places in the Java output.

@@ -39,10 +41,17 @@
         Change a wrong use of a type synonym.

 compiler/options.m:
-        Change `--java-export-ref-out' to be enabled by default.
+        Make `--java-export-ref-out' into a synonym for
+        compiler_sufficiently_recent.  This may be used to test if the compiler
+        supports that behaviour, and for compatibility with existing makefiles.
+
+        Add an option for testing if the compiler generates Java code with
+        generics.

 doc/reference_manual.texi:
-        Update manual to mention use of generics and `--java-export-ref-out'.
+        Update manual to mention use of generics.
+
+        Remove description of `--no-java-export-ref-out'.

 library/exception.m:
 library/io.m:
diff --git a/compiler/ml_proc_gen.m b/compiler/ml_proc_gen.m
index d587370..50ca1af 100644
--- a/compiler/ml_proc_gen.m
+++ b/compiler/ml_proc_gen.m
@@ -226,7 +226,6 @@ ml_gen_export_proc_params(ModuleInfo, PredId,
ProcId, FuncParams) :-
     globals.get_target(Globals, Target),
     (
         Target = target_java,
-        globals.lookup_bool_option(Globals, java_export_ref_out, yes),
         globals.set_option(det_copy_out, bool(no), Globals, GlobalsByRef),
         module_info_set_globals(GlobalsByRef, ModuleInfo, ModuleInfoByRef),
         FuncParamsByRef = ml_gen_proc_params(ModuleInfoByRef, PredId, ProcId),
diff --git a/compiler/options.m b/compiler/options.m
index f56d3c1..522e7ba 100644
--- a/compiler/options.m
+++ b/compiler/options.m
@@ -414,9 +414,6 @@
     ;       put_commit_in_own_func
     ;       put_nondet_env_on_heap

-    % Java back-end compilation model options
-    ;       java_export_ref_out
-
     % IL back-end compilation model options
     ;       verifiable_code
     ;       il_refany_fields
@@ -1307,9 +1304,6 @@ option_defaults_2(compilation_model_option, [
     put_commit_in_own_func              -   bool(no),
     put_nondet_env_on_heap              -   bool(no),

-    % Java back-end compilation model options
-    java_export_ref_out                 -   bool(yes),
-
     % IL back-end compilation model options
     verifiable_code                     -   bool(no),
     il_funcptr_types                    -   bool(no),
@@ -2167,8 +2161,6 @@ long_option("det-copy-out",         det_copy_out).
 long_option("nondet-copy-out",      nondet_copy_out).
 long_option("put-commit-in-own-func",   put_commit_in_own_func).
 long_option("put-nondet-env-on-heap",   put_nondet_env_on_heap).
-% Java back-end compilation model options
-long_option("java-export-ref-out",  java_export_ref_out).
 % IL back-end compilation model options
 long_option("verifiable-code",      verifiable_code).
 long_option("verifiable",           verifiable_code).
@@ -2740,6 +2732,9 @@ long_option("failing-disjunct-in-switch-dup-fix",
                                     compiler_sufficiently_recent).
 long_option("store-at-ref-impure-2008-09-11",
                                     compiler_sufficiently_recent).
+long_option("java-export-ref-out",  compiler_sufficiently_recent).
+long_option("java-generics-2010-04-13",
+                                    compiler_sufficiently_recent).
 long_option("experiment",           experiment).
 long_option("feedback-file",        feedback_file).

@@ -4292,7 +4287,7 @@ options_help_compilation_model -->
         "\tUse an alternative higher-level data representation.",
 %       "--high-level\t\t\t(grades: hl, hl_nest, il, java)",
         "--high-level\t\t\t(grades: hl, il, java)",
-        "\tAn abbreviation for `--high-level-code --high-level-data'.",
+        "\tAn abbreviation for `--high-level-code --high-level-data'."
 % The --gcc-nested-functions option is not yet documented,
 % because it doesn't pass our test suite, and it is
 % probably not very useful.
@@ -4329,11 +4324,7 @@ options_help_compilation_model -->
 %       "--put-nondet-env-on-heap",
 %       "\tAllocate the environment structures used for",
 %       "\tnondeterministic Mercury procedures on the heap,",
-%       "\trather than on the stack.",
-%
-        "--java-export-ref-out",
-        "\tUse pass-by-reference for exported procedures with multiple",
-        "\toutput arguments."
+%       "\trather than on the stack."
 %   ]),
 %   io.write_string("\n      IL back-end compilation model options:\n"),
 %   write_tabbed_lines([
diff --git a/doc/reference_manual.texi b/doc/reference_manual.texi
index 1d3acd7..f853cd5 100644
--- a/doc/reference_manual.texi
+++ b/doc/reference_manual.texi
@@ -7001,8 +7001,8 @@ the length of the array is the number of
elements in the tuple.

 Mercury variables whose types are universally quantified type variables
 will have generic types.
-Mercury variables which are existentially typed will be passed as
- at code{java.lang.Object}.
+Mercury variables whose types are existentially quantified type variables
+will be passed as @code{java.lang.Object}.

 Mercury variables whose type is a Mercury discriminated union type
 will be passed as a Java type whose type name is determined from
@@ -7013,6 +7013,26 @@ The first character of the type name will have
its case inverted,
 and the name may be mangled to satisfy Java lexical rules.
 Generics are used in the Java type for any type parameters.

+ at noindent
+For example, the following Mercury type corresponds to the Java class
+that follows (some implementation details elided):
+
+ at example
+:- type maybe(T)
+    --->    yes(yes_field :: T)
+    ;       no.
+
+public static class Maybe_1<T> @{
+    public static class Yes_1<T> extends Maybe_1 @{
+        public T yes_field;
+        public Yes_1(T x) @{ ... @}
+    @}
+    public static class No_0<T> extends Maybe_1 @{
+        public No_0() @{ ... @}
+    @}
+@}
+ at end example
+
 Mercury array types are mapped to Java array types.

 Java code generated by the Mercury compiler is placed in the @samp{jmercury}
@@ -7041,11 +7061,7 @@ passed or returned at all.
 and in Java modifications to mutable state are done via side effects,
 rather than argument passing.)

-The handling of multiple output arguments depends on the option
- at samp{--java-export-ref-out}.  It is enabled by default.
-
- at noindent
-With @samp{--java-export-ref-out}:
+The handling of multiple output arguments is as follows.

 If the Mercury procedure is deterministic and has no output arguments,
 then the return type of the Java function is @samp{void}; if it has
@@ -7067,25 +7083,6 @@ same way as multiple outputs for deterministic
procedures, using the
 @samp{Ref} class.  On failure the values of the @samp{val} fields are
 undefined.

- at noindent
-With @samp{--no-java-export-ref-out}:
-
-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[]}.
- at c end description of --no-java-export-ref-out
-
 Mercury lists can be manipulated by Java code using the following methods,
 which are defined by the Mercury implementation.

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