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

[Julien Fischer]

On Fri, 9 Apr 2010, Peter Wang wrote:

> Branches: main, 10.04
>
> Make the Java backend use generics in the output.  We do not use generics
> everywhere, only where it interfaces with hand written code:
>
> - in classes generated for Mercury types
> - in the signatures of foreign_exported procedures
> - in the variables which interface with foreign_proc code
>
> Make `--java-export-ref-out' be the default.  Both changes will require users
> to update their code so we might as well make them together.
>
>
> compiler/mlds.m:
> compiler/ml_proc_gen.m:
> compiler/ml_type_gen.m:
>        Record type parameters for classes generated for Mercury types.
>
>        Record universally quantified type variables for exported procedures.
>
> compiler/mlds_to_java.m:
>        Output type variables in the appropriate places in the Java output.
>
> compiler/ml_code_util.m:
>        Add functions to return the MLDS types for jmercury.runtime.MercuryType
>        and MercuryEnum.
>
> compiler/ml_elim_nested.m:
> compiler/ml_global_data.m:
> compiler/ml_optimize.m:
> compiler/ml_tailcall.m:
> compiler/ml_util.m:
> compiler/mlds_to_c.m:
> compiler/mlds_to_gcc.m:
> compiler/mlds_to_il.m:
>        Conform to previous changes.
>
> compiler/hlds_pred.m:
>        Change a wrong use of a type synonym.
>
> compiler/options.m:
>        Change `--java-export-ref-out' to be enabled by default.
>
> doc/reference_manual.texi:
>        Update manual to mention use of generics and `--java-export-ref-out'.
>
> library/exception.m:
> library/io.m:
> library/list.m:
> library/rtti_implementation.m:
> library/string.m:
> library/type_desc.m:
>        Update code to comply with use of generics and `--java-export-ref-out'.
>
> tests/hard_coded/exceptions/Mmakefile:
>        Allow `java' grade testing in this directory.

...

> diff --git a/doc/reference_manual.texi b/doc/reference_manual.texi
> index 0930414..1d3acd7 100644
> --- a/doc/reference_manual.texi
> +++ b/doc/reference_manual.texi
> @@ -6999,9 +6999,11 @@ passed as the corresponding Java type.
> Mercury tuple types are passed as @samp{java.lang.Object[]} where
> the length of the array is the number of elements in the tuple.
>
> -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 ...

> @code{java.lang.Object}.
> -Mercury array types are mapped to Java array types.
> +
> Mercury variables whose type is a Mercury discriminated union type
> will be passed as a Java type whose type name is determined from
> the Mercury type name (ignoring any type parameters) followed by
> @@ -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.

> +Mercury array types are mapped to Java array types.
>
> Java code generated by the Mercury compiler is placed in the @samp{jmercury}
> package.  Mercury module qualifiers are converted into a Java class name by
> @@ -7030,27 +7035,14 @@ whose result has an input mode, then the Mercury function result is
> appended to the list of input parameters, so that the Mercury function
> result becomes the last parameter to the corresponding Java function.
>
> -The handling of multiple output arguments depends on the option
> - at samp{--java-export-ref-out}.  It is disabled by default, but in the
> -future will become enabled by default.
> -
> - at noindent
> -Without @samp{--java-export-ref-out}:
> +Arguments of type @samp{io.state} or @samp{store.store(_)} are not
> +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.)
>
> -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[]}.
> +The handling of multiple output arguments depends on the option
> + at samp{--java-export-ref-out}.  It is enabled by default.
>
> @noindent
> With @samp{--java-export-ref-out}:
> @@ -7075,21 +7067,35 @@ same way as multiple outputs for deterministic procedures, using the
> @samp{Ref} class.  On failure the values of the @samp{val} fields are
> undefined.
>
> -Arguments of type @samp{io.state} or @samp{store.store(_)} are not
> -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.)
> + 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

Is it worth documenting --no-java-export-ref-out anymore?

The rest looks fine.

Julien.

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